@terminalfour/terminalfour-js 1.0.0-rc.1

package/docs/navigation.md

@@ -0,0 +1,134 @@
+# Navigation Objects
+
+Navigation objects control site navigation during publishing. terminalfour-js supports all 19 types, including each type's configuration and validation rules.
+
+## List and filter navigation objects
+
+```typescript
+const all = await t4.navigation.list();
+for (const navigation of all) {
+  console.log(navigation.id, navigation.name, navigation.type, navigation.enabled);
+}
+
+const breadcrumbs = await t4.navigation.list({ type: 'breadcrumbs' });
+const sitemaps = await t4.navigation.list({ type: 'site-map' });
+```
+
+Each `NavigationSummary` contains:
+
+| Property | Type | Description |
+|---|---|---|
+| `id` | `number` | Navigation object ID |
+| `name` | `string` | Display name |
+| `description` | `string` | Description |
+| `type` | `string` | Type code listed below |
+| `typeName` | `string` | Human-readable type name |
+| `enabled` | `boolean` | Whether the navigation is active |
+
+## Get a navigation object
+
+```typescript
+const navigation = await t4.navigation.get(181);
+console.log(navigation.name);            // 'A-Z Navigation Demo'
+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.properties);      // properties vary by type
+```
+
+Type-specific properties use JavaScript booleans, numbers, and arrays. The SDK omits internal and derived fields.
+
+| Shared property | Mutable | Description |
+|---|---|---|
+| `name` | yes | Display name |
+| `description` | yes | Description |
+| `enabled` | yes | Whether the navigation is active |
+| `cachingEnabled` | yes | Whether output caching is enabled |
+| `previewEnabled` | yes | Whether preview mode is enabled |
+| `properties` | yes | Type-specific configuration |
+
+## Create a navigation object
+
+```typescript
+await t4.navigation.create({
+  type: 'breadcrumbs',
+  name: 'Main Breadcrumbs',
+  description: 'Site breadcrumb trail',
+  properties: {
+    separator: ' > ',
+    useLinks: true,
+    hideHome: true,
+  },
+});
+```
+
+Only `type` and `name` are required. Properties have default values.
+
+## Update a navigation object
+
+### Direct update
+
+```typescript
+const navigation = await t4.navigation.update(181, {
+  name: 'Renamed',
+  enabled: false,
+  properties: {
+    beforeHtml: '<div>',
+  },
+});
+```
+
+`update()` merges `properties` with existing values. Pass only the keys to change:
+
+```typescript
+await t4.navigation.update(10, {
+  properties: { separator: ' / ' },
+});
+```
+
+Every other property remains unchanged. A navigation object's `type` cannot change after creation, so `update()` does not accept it.
+
+### Mutable item
+
+```typescript
+const navigation = await t4.navigation.get(181);
+navigation.name = 'Renamed';
+navigation.enabled = false;
+navigation.properties.beforeHtml = '<div>';
+await navigation.save();
+```
+
+## Delete a navigation object
+
+```typescript
+await t4.navigation.delete(181);
+```
+
+## Navigation types
+
+| Type name | Code | Guide |
+|---|---|---|
+| A to Z Navigation | `a-to-z` | [Details](./navigation/a-to-z.md) |
+| Breadcrumbs | `breadcrumbs` | [Details](./navigation/breadcrumbs.md) |
+| CSS Selector | `css-selector` | [Details](./navigation/css-selector.md) |
+| Generate File | `generate-file` | [Details](./navigation/generate-file.md) |
+| Keyword Search Content | `keyword-search` | [Details](./navigation/keyword-search.md) |
+| Language Switcher | `language-switcher` | [Details](./navigation/language-switcher.md) |
+| Link Menu | `link-menu` | [Details](./navigation/link-menu.md) |
+| Pagination | `pagination` | [Details](./navigation/pagination.md) |
+| Previous/Next Fulltext Content | `previous-next-fulltext` | [Details](./navigation/previous-next-fulltext.md) |
+| Publish to One File | `publish-to-one-file` | [Details](./navigation/publish-to-one-file.md) |
+| Related Content | `related-content` | [Details](./navigation/related-content.md) |
+| Related Section Branch | `related-section-branch` | [Details](./navigation/related-section-branch.md) |
+| Return to Index | `return-to-index` | [Details](./navigation/return-to-index.md) |
+| Section Details | `section-details` | [Details](./navigation/section-details.md) |
+| Section Iterator | `section-iterator` | [Details](./navigation/section-iterator.md) |
+| Section Meta Info | `section-meta-info` | [Details](./navigation/section-meta-info.md) |
+| Site Map | `site-map` | [Details](./navigation/site-map.md) |
+| Top Content | `top-content` | [Details](./navigation/top-content.md) |
+| Top Stories | `top-stories` | [Details](./navigation/top-stories.md) |
+
+---
+
+**Previous:** [Channels](./channels.md) · **Next:** [Handlebars](./handlebars.md)

package/docs/page-layouts.md

@@ -0,0 +1,71 @@
+# Page Layouts
+
+Use `t4.pageLayouts` to manage page layout code, syntax, processors, and file extensions.
+
+## List and read page layouts
+
+```typescript
+const layouts = await t4.pageLayouts.list();
+// [{ id: 5, name: 'Main Layout', description: 'Default page layout' }]
+
+const layout = await t4.pageLayouts.get(5);
+```
+
+A full page layout includes:
+
+| Property | Example or meaning |
+|---|---|
+| `name` | Layout name |
+| `description` | Layout description |
+| `headerCode` | Header markup or code |
+| `footerCode` | Footer markup or code |
+| `fileExtension` | Output file extension |
+| `syntax` | Syntax such as `'HTML/XML'` |
+| `processor` | Processor such as `'handlebars'` |
+
+## Create a page layout
+
+```typescript
+await t4.pageLayouts.create({
+  name: 'My Layout',
+  description: 'A custom page layout',
+  headerCode: '<!DOCTYPE html><html><head></head><body>',
+  footerCode: '</body></html>',
+  syntax: 'HTML/XML',      // optional
+  processor: 'handlebars', // optional; default: 'handlebars'
+  fileExtension: 'html',   // optional
+});
+```
+
+Processor options are `'handlebars'`, `'t4-tags'`, and `'programmable-layouts'`. The default is `'handlebars'`.
+
+## Update a page layout
+
+### Direct update
+
+```typescript
+await t4.pageLayouts.update(5, {
+  name: 'Renamed',
+  headerCode: '<!-- updated -->',
+});
+```
+
+### Mutable item
+
+```typescript
+const layout = await t4.pageLayouts.get(5);
+layout.name = 'Renamed';
+layout.headerCode = '<!-- updated -->';
+layout.processor = 't4-tags';
+await layout.save();
+```
+
+## Delete a page layout
+
+```typescript
+await t4.pageLayouts.delete(5);
+```
+
+---
+
+**Previous:** [Groups & Users](./groups-and-users.md) · **Next:** [Media](./media.md)

package/docs/sections.md

@@ -0,0 +1,224 @@
+# Sections
+
+`t4.section(id)` creates a lightweight `SectionRef` without making an API request. Use the reference to read or change that section.
+
+## Contents
+
+- [Read and update a section](#read-and-update-a-section)
+- [Create, delete, purge, or move](#create-delete-purge-or-move)
+- [Navigate the section tree](#navigate-the-section-tree)
+- [Manage section configuration](#manage-section-configuration)
+- [Publish](#publish)
+
+## Read and update a section
+
+```typescript
+const section = await t4.section(233).get();
+```
+
+`get()` returns a mutable `SectionItem`:
+
+| Property | Type | Mutable | Description |
+|---|---|---|---|
+| `id` | `number` | no | Section ID |
+| `parentId` | `number \| null` | no | Parent section ID |
+| `name` | `string` | yes | Section name |
+| `show` | `boolean` | yes | Visible in navigation |
+| `status` | `string` | yes | `'approved'`, `'pending'`, or `'inactive'` |
+| `outputUri` | `string` | yes | Output URI for publishing |
+| `filename` | `string` | yes | Output filename |
+| `archive` | `boolean` | yes | Whether this is an archive section |
+| `path` | `string \| null` | no | Breadcrumb path (`'Home » Site » Section'`) |
+| `pathMembers` | `number[]` | no | Section IDs in the path |
+| `lastModified` | `Date \| null` | no | Last modification date |
+| `accessControl` | `{ active, enabled }` | no | Access control state |
+| `customFields` | `Record<string, unknown> \| null` | yes | Resolved metadata content fields, or `null` |
+
+### Direct update
+
+Use `update()` when you already know the values to change:
+
+```typescript
+await t4.section(233).update({
+  name: 'Renamed',
+  show: false,
+  status: 'pending',
+  customFields: { 
+    Title: 'New Title' 
+  },
+});
+```
+
+### Mutable item
+
+Use `get()` and `save()` when you need to inspect the current section first:
+
+```typescript
+const section = await t4.section(233).get();
+section.name = 'Renamed Section';
+section.show = false;
+section.outputUri = 'new-uri';
+await section.save();
+```
+`customFields` is `null` only when the instance has no section metadata content type configured at all. When a metadata type exists, `customFields` is an object (empty if no fields are set).
+
+The SDK will throw when no metadata content type is configured on the instance and you attempt add customFields.
+
+## Create, delete, purge, or move
+
+### Create a child section
+
+```typescript
+const child = await t4.section(233).addSection({
+  name: 'New Section',
+  show: true,                              // default: true
+  status: 'approved',                      // default: 'approved'
+  customFields: { Title: 'Custom Title' }, // optional
+});
+```
+
+The new section inherits channels, page layouts, access control, and metadata types from its parent.
+
+When the instance has a section metadata content type configured, `addSection()` always creates a metadata content instance for the new section, whether or not you pass `customFields`.
+
+### Delete, purge, or move
+
+```typescript
+await t4.section(500).delete();   // soft delete: sets status to inactive
+await t4.section(500).purge();    // permanent removal; section must be inactive first
+await t4.section(500).move(233);  // move under section 233
+```
+
+## Navigate the section tree
+
+### Direct children
+
+Use `subsections()` for a one-level lookup:
+
+```typescript
+const children = await t4.section(233).subsections();
+// [{ id: 500, name: 'Child', lastModified: Date }]
+```
+
+### Full tree or subtree
+
+```typescript
+const tree = await t4.siteStructure.tree(); // full site structure
+const subTree = await t4.section(6758).tree(); // subtree from section 6758
+```
+
+Tree nodes contain `id`, `name`, `status`, and optional `children`. `siteStructure.tree()` retrieves the entire hierarchy in one request, so prefer `subsections()` for lighter lookups on large sites.
+
+## Manage section configuration
+
+### Channels
+
+```typescript
+const channels = await t4.section(233).channels();
+// [{ id: 1, name: 'Default Channel' }]
+```
+
+### Owner
+
+```typescript
+const owner = await t4.section(233).owner();
+// { id: 30, type: 'contributor', username: 'j.smith',
+//   firstName: 'Jane', lastName: 'Smith', emailAddress: 'jane@example.com' }
+```
+
+`type` is the user's role: `'admin'`, `'power-user'`, `'moderator'`, `'contributor'`, or `'visitor'`.
+
+### Metadata
+
+```typescript
+const meta = await t4.section(233).metaDatas();
+// { 'og:title': 'Page Title', 'description': 'A description' }
+
+await t4.section(233).setMetaDatas({
+  'og:title': 'New Title',
+  'description': 'Updated description',
+});
+```
+
+`setMetaDatas()` merges the supplied values with existing metadata. It does not replace the whole object. Invalid tag names produce an error that lists the valid options.
+
+### Page layouts
+
+```typescript
+const layouts = await t4.section(233).pageLayouts();
+// [
+//   {
+//     channel: { id: 1, name: 'Default Channel' },
+//     pageLayout: { id: 5, name: 'Main Layout', inherited: false },
+//     childPageLayout: { id: 10, name: 'Child Layout' },
+//   },
+//   {
+//     channel: { id: 3, name: 'Preview' },
+//     pageLayout: { id: 3446, name: 'Preview Layout', inherited: true },
+//     childPageLayout: null,
+//   },
+// ]
+```
+
+| Value | Meaning |
+|---|---|
+| `pageLayout` | Layout applied to this section. `inherited: true` means it comes from a parent. |
+| `childPageLayout` | Layout that descendant sections inherit. |
+
+Set layouts by channel. The operation is additive, so it changes only the channels you pass:
+
+```typescript
+await t4.section(233).setPageLayouts([
+  { channelId: 1, pageLayout: 99 },
+  { channelId: 3, childPageLayout: 200 },
+]);
+
+await t4.section(233).setPageLayouts([
+  { channelId: 1, pageLayout: null }, // clear this layout
+]);
+```
+
+### Edit rights
+
+```typescript
+const rights = await t4.section(233).editRights();
+// {
+//   users: [{ id, username, firstName, lastName, emailAddress, inherited: false }],
+//   groups: [{ id, name, inherited: true }]
+// }
+
+await t4.section(233).setEditRights({ users: [30, 61], groups: [1] });
+await t4.section(233).removeEditRights({ users: [30] });
+```
+
+`setEditRights()` adds and deduplicates rights.
+
+### Content types
+
+```typescript
+const types = await t4.section(233).contentTypes();
+// [{ id: 44, name: 'Article', description: '...', scope: 'branch' }]
+
+await t4.section(233).setContentTypes([
+  { id: 44, scope: 'branch' },
+  { id: 343, scope: 'section' },
+]);
+
+await t4.section(233).removeContentTypes([44]);
+```
+
+`setContentTypes()` merges the supplied types with the existing configuration.
+
+## Publish
+
+```typescript
+await t4.section(237).publish(); // single section; selects the channel if there is only one
+await t4.section(237).publish({ branch: true }); // entire branch
+await t4.section(237).publish({ channelId: 1, branch: true }); // selected channel
+```
+
+When a section belongs to multiple channels, you must supply `channelId`. Otherwise, the SDK throws an error that lists the available channels.
+
+---
+
+**Previous:** [Getting Started](./getting-started.md) · **Next:** [Content](./content.md)

package/docs/typescript.md

@@ -0,0 +1,124 @@
+# TypeScript Reference
+
+The package exports its public classes, interfaces, and type aliases. Import runtime values normally and use `import type` for type-only imports.
+
+## Runtime exports
+
+```typescript
+import {
+  T4Client,
+  T4ApiError,
+  ContentItem,
+  SectionItem,
+  SectionRef,
+  SiteStructure,
+  MediaCategoryRef,
+  MediaCategoryItem,
+  MediaItem,
+  MediaLibrary,
+  ContentType,
+  Layout,
+  List,
+  Group,
+  User,
+  PageLayout,
+  MediaType,
+  MediaTypeResource,
+  NavigationResource,
+  NavigationObject,
+  Channel,
+  ChannelResource,
+  Handlebars,
+  HandlebarsItem,
+  HandlebarsContentResource,
+  NAVIGATION_TYPE_NAMES,
+} from '@terminalfour/terminalfour-js';
+```
+
+## Type-only exports
+
+```typescript
+import type {
+  // Client configuration
+  T4ClientConfig,
+  LanguageOption,
+
+  // Content
+  ContentDTO,
+  CreateContentData,
+  UpdateContentData,
+  DateInput,
+
+  // Content types
+  ContentTypeData,
+  ContentTypeFieldDef,
+
+  // Sections
+  AddSectionData,
+  HierarchyNode,
+  GetTreeOptions,
+  SectionTreeNode,
+  Owner,
+
+  // Media
+  FileInput,
+  MediaFileInput,
+  MediaListItem,
+  MediaCategoryNode,
+  MediaElementUpload,
+  SectionContentLinkInput,
+
+  // Media types
+  MediaTypeLayout,
+  MediaTypeData,
+
+  // Navigation
+  NavigationType,
+  NavigationSummary,
+
+  // Channels
+  ChannelSummary,
+  ChannelLanguage,
+  Microsite,
+
+  // Lists
+  ListSummary,
+  ListItemData,
+
+  // Groups
+  GroupData,
+  GroupMember,
+
+  // Users
+  UserData,
+  AuthMethods,
+  AuthMethodValue,
+
+  // Page layouts
+  PageLayoutSummary,
+
+  // Handlebars
+  HandlebarsItemSummary,
+  HelperSummary,
+  PartialSummary,
+  Helper,
+  Partial,
+} from '@terminalfour/terminalfour-js';
+```
+
+## Module formats
+
+The package supports `import` with ESM and `require` with CommonJS. TypeScript declaration files (`.d.ts`) are included for both output formats.
+
+The shared `tsconfig.json` uses the ES2020 module mode so editors can check source files that use dynamic imports. `tsconfig.cjs.json` overrides that setting with CommonJS for the CJS build.
+
+## Build and test
+
+```bash
+npm run build # writes dual ESM/CJS output to dist/
+npm test      # runs Vitest
+```
+
+---
+
+**Previous:** [Error Handling](./error-handling.md)

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@terminalfour/terminalfour-js",
+  "version": "1.0.0-rc.1",
+  "description": "JavaScript / TypeScript SDK for the Terminalfour Web Services REST API",
+  "keywords": [
+    "terminalfour",
+    "t4",
+    "cms",
+    "sdk",
+    "rest-api",
+    "content-management",
+    "typescript"
+  ],
+  "homepage": "https://github.com/TERMINALFOUR/terminalfour-js#readme",
+  "bugs": {
+    "url": "https://github.com/TERMINALFOUR/terminalfour-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TERMINALFOUR/terminalfour-js.git"
+  },
+  "author": "Terminalfour Solutions Limited",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "test": "vitest --run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "fast-check": "^4.1.1",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.1"
+  },
+  "license": "Elastic-2.0"
+}