@terminalfour/terminalfour-js 1.0.0-rc.1

package/docs/getting-started.md

@@ -0,0 +1,146 @@
+# Getting Started
+
+Install and configure terminalfour-js in server-side TypeScript code, then verify the connection and choose language and cache settings.
+
+## Install
+
+```bash
+npm install @terminalfour/terminalfour-js
+```
+
+The package includes TypeScript declarations and supports both ESM (`import`) and CommonJS (`require`). It requires **Node 18 or later** because it uses the built-in `fetch`, `FormData`, and `Error.cause`.
+
+## Create a client
+
+```typescript
+import { T4Client } from '@terminalfour/terminalfour-js';
+
+const t4 = new T4Client({
+  baseUrl: 'https://mysite.edu/terminalfour/rs',
+  apiToken: 'your-api-token',
+});
+```
+
+### Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | required | T4 instance REST API URL |
+| `apiToken` | `string` | required | API authentication token |
+| `language` | `string` | `'en'` | Default language for supported operations |
+| `concurrency` | `number` | `10` | Maximum parallel HTTP requests |
+
+### `baseUrl` requirements
+
+`baseUrl` must be an absolute `http` or `https` URL. The client strips trailing slashes, so these values are equivalent:
+
+```typescript
+baseUrl: 'https://mysite.edu/terminalfour/rs'
+baseUrl: 'https://mysite.edu/terminalfour/rs/'
+```
+
+The constructor rejects a value that is not a parseable absolute URL or uses a protocol other than `http` or `https`:
+
+```typescript
+new T4Client({ baseUrl: 'mysite.edu/terminalfour/rs', apiToken: '...' });
+// Error: T4Client baseUrl "mysite.edu/terminalfour/rs" is not a valid absolute URL.
+```
+
+**Important:** An `http://` URL logs a warning because every request sends the API token in an `Authorization` header, and plain HTTP transmits it in cleartext. Always use `https://` unless you are testing against a local instance.
+
+## Keep the client server-side
+
+The `apiToken` grants full read/write access to your T4 instance. Browser bundles are publicly readable, so sending the token to front-end code exposes it to every visitor, regardless of your application's authentication.
+
+The SDK prevents this by throwing when code constructs a client in a browser. You cannot disable this check.
+
+```typescript
+// Browser code: throws
+new T4Client({ baseUrl, apiToken });
+// Error: T4Client cannot be used in a browser. The apiToken is a full-privilege
+// credential and anything in front-end code is publicly readable...
+```
+
+Construct the client in an API route, serverless function, or backend service. Return only the data the browser needs:
+
+```typescript
+const t4 = new T4Client({
+  baseUrl: process.env.T4_BASE_URL!,
+  apiToken: process.env.T4_API_TOKEN!,
+});
+
+const items = await t4.section(482).content.list();
+// Return `items` from your server endpoint. The token stays on the server.
+```
+
+The guard checks for both `window` and `window.document`, so it blocks only browser environments. Node, Deno, Bun, Cloudflare Workers, similar edge runtimes, and Web Workers continue to work.
+
+## Set the language
+
+Configure a client default when you need a language other than `en`:
+
+```typescript
+const t4 = new T4Client({
+  baseUrl: 'https://mysite.edu/terminalfour/rs',
+  apiToken: 'your-api-token',
+  language: 'fr',
+  concurrency: 5,
+});
+```
+
+For sections, content, and lists, the SDK resolves language in this order:
+
+1. Per-call `{ language }` option
+2. Client `language`
+3. `'en'`
+
+```typescript
+await t4.section(482).content.list();                  // uses client default 'fr'
+await t4.section(482).content.list({ language: 'de' }); // overrides this call
+```
+
+Other resources use fixed languages:
+
+| Resource | Language |
+|---|---|
+| Media items | `smxx` (language-independent) |
+| Media categories and media library | `en` |
+| Page layouts, content layouts, channels, groups, and users | `en` |
+
+## Inspect the T4 instance
+
+The client provides four read-only platform methods:
+
+| Method | Returned data | Example property |
+|---|---|---|
+| `about()` | T4 version, uptime, OS, Java, and servlet details | `info.t4.version` is `'8.4.2-FINAL'`; `info.t4.uptime` is a `Date`; `info.os.name` is `'Linux'`; `info.java.version` is `'11.0.18'` |
+| `database()` | Database connection details | `db.name` is `'MySQL'`; `db.version` is `'8.0.32'` |
+| `environment()` | Environment configuration | `env['max_upload_size']` is `'50000'` |
+| `licence()` | Licence usage | `lic.remaining` may be `14121` content items |
+
+```typescript
+const info = await t4.about();
+const db = await t4.database();
+const env = await t4.environment();
+const lic = await t4.licence();
+```
+
+## Debug requests
+
+Set `T4_DEBUG=1` to log HTTP requests and internal warnings:
+
+```bash
+T4_DEBUG=1 node my-script.js
+```
+
+## Refresh cached data
+
+The SDK caches content type templates, list values, element type definitions, and other lookup data for five minutes. You can clear every SDK cache after changing configuration during with:
+
+```typescript
+t4.clearCache();
+```
+
+---
+
+**Next:** [Sections](./sections.md)

package/docs/groups-and-users.md

@@ -0,0 +1,167 @@
+# Groups and Users
+
+Use `t4.groups` to manage memberships and `t4.users` to manage accounts, authentication methods, and custom fields.
+
+## Groups
+
+### List and read groups
+
+```typescript
+const groups = await t4.groups.list();
+// [{ id, name, description, membersCount, enabled, children, parentIds }]
+
+const group = await t4.groups.get(1);
+```
+
+A full group includes `name`, `description`, `enabled`, `emailAddress`, `children`, and `members`. `children` contains child group IDs. Each member includes `id`, `username`, `firstName`, `lastName`, `emailAddress`, and `userLevel`.
+
+```typescript
+for (const member of group.members) {
+  console.log(
+    member.id,
+    member.username,
+    member.firstName,
+    member.lastName,
+    member.emailAddress,
+    member.userLevel,
+  );
+}
+```
+
+### Create a group
+
+```typescript
+await t4.groups.create({
+  name: 'Editors',
+  description: 'Content editors',
+  members: [38, 61], // user IDs; the SDK resolves full user objects
+  enabled: true,
+});
+```
+
+A group requires at least one member.
+
+### Update a group
+
+#### Direct update
+
+```typescript
+await t4.groups.update(1, { name: 'Renamed', enabled: false });
+```
+
+#### Mutable item
+
+```typescript
+const group = await t4.groups.get(1);
+group.name = 'Renamed';
+group.addMembers([62, 63]);
+group.removeMembers([66]);
+await group.save();
+```
+
+After `save()`, the SDK refreshes `members` to reflect the changes.
+
+### Delete a group
+
+```typescript
+await t4.groups.delete(42);
+```
+
+## Users
+
+### List users
+
+```typescript
+const users = await t4.users.list();
+// [{ id, username, firstName, lastName, emailAddress, userLevel, enabled, accountLocked, lastLogin }]
+
+const admins = await t4.users.list({ userLevel: 'admin' });
+```
+
+User levels are `'admin'`, `'power-user'`, `'moderator'`, `'contributor'`, and `'visitor'`.
+
+### Get a user
+
+```typescript
+const user = await t4.users.get(30);
+```
+
+| Property | Example or meaning |
+|---|---|
+| `username` | Account username |
+| `firstName`, `lastName` | User's name |
+| `emailAddress` | Email address |
+| `userLevel` | `'contributor'` |
+| `defaultLanguage` | `'en'` |
+| `enabled` | Whether the account is enabled |
+| `lastLogin` | `Date` or `null` when the user has never logged in |
+| `groups` | `[{ id: 1, name: 'Editors' }]` |
+| `customFields` | `{ Department: 'Engineering' }` or `null` |
+
+### Authentication methods
+
+```typescript
+console.log(user.authMethods);
+// {
+//   local: true,
+//   ldap: { enabled: true, identifier: 'uid=jsmith,ou=people,dc=example,dc=com' },
+//   saml: false,
+//   cas: false,
+//   remoteuser: false,
+// }
+
+user.authMethods.saml = { enabled: true, identifier: 'saml-user-id' };
+await user.save();
+```
+
+- `local` and `remoteuser` are booleans and never have identifiers.
+- `ldap`, `saml`, and `cas` are `boolean | { enabled: boolean; identifier: string }`.
+
+### Create a user
+
+```typescript
+await t4.users.create({
+  username: 'new.user',
+  firstName: 'New',
+  lastName: 'User',
+  emailAddress: 'new@example.com',
+  password: 'SecureP@ss123!',
+  userLevel: 'contributor',     // optional; default: 'contributor'
+  defaultLanguage: 'en',        // optional; default: 'en'
+  enabled: true,                // optional; default: true
+  authMethods: { local: true }, // optional; default: { local: true }
+});
+```
+
+### Update a user
+
+#### Direct update
+
+```typescript
+await t4.users.update(30, {
+  firstName: 'Updated',
+  userLevel: 'moderator',
+});
+```
+
+#### Mutable item
+
+```typescript
+const user = await t4.users.get(30);
+user.firstName = 'Updated';
+user.password = 'NewP@ssword456!';
+if (user.customFields) {
+  user.customFields['Department'] = 'Marketing';
+}
+await user.save();
+```
+
+### Delete a user
+
+```typescript
+await t4.users.delete(68);
+```
+
+---
+
+**Previous:** [Lists](./lists.md) · **Next:** [Page Layouts](./page-layouts.md)

package/docs/handlebars.md

@@ -0,0 +1,145 @@
+# Handlebars
+
+Use `t4.handlebars.helpers` for custom helper functions and `t4.handlebars.partials` for reusable template fragments.
+
+```typescript
+t4.handlebars.helpers
+t4.handlebars.partials
+```
+
+Helpers and partials are stored as content items in hidden sections. Both resources expose `list()`, `get(name)`, `create()`, `update(name)`, `delete(name)`, and `purge(name)`. Any method that accepts a name also accepts a numeric ID.
+
+## Contents
+
+- [Shared behavior](#shared-behavior)
+- [Helpers](#helpers)
+- [Partials](#partials)
+- [Errors and operational notes](#errors-and-operational-notes)
+
+## Shared behavior
+
+| Operation | Behavior |
+|---|---|
+| `list()` | Returns summary objects with `id`, `name`, and `lastModified` |
+| `get(nameOrId)` | Returns the full mutable item, including `code` |
+| `create({ name, code })` | Requires both values, enforces a unique name, and creates an approved item |
+| `update(nameOrId, data)` | Applies a direct update and saves with approved status |
+| `save()` | Saves a mutable item with approved status |
+| `delete(nameOrId)` | Soft deletes the item |
+| `purge(nameOrId)` | Permanently removes the item |
+
+## Helpers
+
+Custom helpers are available in content layouts.
+
+### List and get helpers
+
+```typescript
+const helpers = await t4.handlebars.helpers.list();
+// [{ id: 100, name: 'formatDate', lastModified: Date }, ...]
+
+const helper = await t4.handlebars.helpers.get('formatDate');
+console.log(helper.name);         // 'formatDate'
+console.log(helper.code);         // 'module.exports = function(date) { ... }'
+console.log(helper.lastModified); // Date object
+```
+
+`list()` returns summaries. Call `get(name)` for the code. You can also retrieve the same helper by ID with `t4.handlebars.helpers.get(100)`.
+
+### Create a helper
+
+```typescript
+const helper = await t4.handlebars.helpers.create({
+  name: 'truncate',
+  code: 'function(context, options) { return context.substring(0, options.hash('len')); }',
+});
+```
+
+### Direct update
+
+```typescript
+const updated = await t4.handlebars.helpers.update('formatDate', {
+  code: 'function(context, options) { return new Date(context).toISOString(); }',
+});
+```
+
+### Mutable item
+
+```typescript
+const helper = await t4.handlebars.helpers.get('formatDate');
+helper.name = 'formatDateISO';
+helper.code = 'function(context, options) { return new Date(context).toISOString().split("T")[0]; }';
+await helper.save();
+```
+
+### Delete or purge a helper
+
+```typescript
+await t4.handlebars.helpers.delete('truncate'); // soft delete
+await t4.handlebars.helpers.purge('truncate');  // permanent removal
+```
+
+## Partials
+
+Partials are reusable template fragments included in content layouts with `{{> partialName}}`.
+
+### List and get partials
+
+```typescript
+const partials = await t4.handlebars.partials.list();
+// [{ id: 200, name: 'header', lastModified: Date }, ...]
+
+const partial = await t4.handlebars.partials.get('header');
+console.log(partial.name);         // 'header'
+console.log(partial.code);         // '<header><h1>{{sectionName}}</h1></header>'
+console.log(partial.lastModified); // Date object
+```
+
+### Create a partial
+
+```typescript
+const partial = await t4.handlebars.partials.create({
+  name: 'footer',
+  code: '<footer><p>&copy; {{channelName}}</p></footer>',
+});
+```
+
+### Direct update
+
+```typescript
+const updated = await t4.handlebars.partials.update('header', {
+  code: '<header class="main"><h1>{{sectionName}}</h1></header>',
+});
+```
+
+### Mutable item
+
+```typescript
+const partial = await t4.handlebars.partials.get('header');
+partial.name = 'site-header';
+partial.code = '<header class="main"><h1>{{sectionName}}</h1></header>';
+await partial.save();
+```
+
+### Delete or purge a partial
+
+```typescript
+await t4.handlebars.partials.delete('footer'); // soft delete
+await t4.handlebars.partials.purge('footer');  // permanent removal
+```
+
+## Errors and operational notes
+
+- A duplicate name on create produces an error.
+- A missing name produces an error that lists available names.
+- If multiple items have the same name, the SDK reports their IDs so you can use a numeric ID.
+- Names are the primary interface; IDs provide a fallback when a name is ambiguous.
+- Every create, update, and save forces approved status so Handlebars can use the item immediately.
+- Operations always use language `en`, regardless of the client's configured language. Helpers and partials are language-independent.
+- Hidden section and content type IDs are read from configuration endpoints on first use and cached for five minutes.
+- `t4.clearCache()` invalidates those cached configuration values.
+- Helpers use a `Function Code` element; partials use a `Code` element. The SDK handles the difference.
+
+---
+
+**Previous:** [Navigation](./navigation.md) · **Next:** [Error Handling](./error-handling.md)

package/docs/lists.md

@@ -0,0 +1,98 @@
+# Lists
+
+Use `t4.lists` to manage list definitions and their items.
+
+## List and read lists
+
+```typescript
+const lists = await t4.lists.list();
+// [{ id: 71, name: 'Sizes', description: 'Size options' }]
+
+const list = await t4.lists.get(71);
+```
+
+| Property | Example |
+|---|---|
+| `name` | `'Sizes'` |
+| `description` | List description |
+| `isForcedLanguage` | `false` |
+| `isDefaultLanguage` | `false` |
+| `primaryGroup` | `0` |
+| `sharedGroups` | `[]` |
+| `items` | Item definitions keyed by name |
+
+Items are keyed by name:
+
+```typescript
+console.log(list.items);
+// {
+//   Large: { name: 'Large', value: 'lg', selected: true },
+//   Small: { name: 'Small', value: 'sm', selected: false },
+// }
+
+list.items['Large'].value = 'updated';
+list.items['Large'].selected = false;
+await list.save();
+```
+
+## Create a list
+
+```typescript
+const newList = await t4.lists.create({
+  name: 'Priorities',
+  description: 'Priority levels',
+  items: [
+    { name: 'High', value: 'high', selected: true },
+    { name: 'Medium', value: 'medium' },
+    { name: 'Low', value: 'low' },
+  ],
+});
+```
+
+`isForcedLanguage` and `isDefaultLanguage` both default to `false`. They cannot both be `true`; the SDK validates this during create and save.
+
+## Update a list
+
+### Direct update
+
+```typescript
+await t4.lists.update(71, {
+  name: 'Renamed',
+  description: 'Updated',
+});
+```
+
+### Mutable item
+
+```typescript
+const list = await t4.lists.get(71);
+list.name = 'Renamed';
+list.description = 'Updated';
+await list.save();
+```
+
+## Add or remove items
+
+```typescript
+const list = await t4.lists.get(71);
+
+list.addItem({ name: 'Extra Large', value: 'xl', selected: false });
+list.removeItem('Small');
+await list.save();
+```
+
+Add `sublistId` when an item opens a sublist:
+
+```typescript
+list.addItem({ name: 'Soccer', value: 'soccer', sublistId: 72 });
+```
+
+## Delete a list
+
+```typescript
+await t4.lists.delete(71);
+```
+
+---
+
+**Previous:** [Content Types](./content-types.md) · **Next:** [Groups & Users](./groups-and-users.md)

package/docs/media-types.md

@@ -0,0 +1,111 @@
+# Media Types
+
+Media types define permitted file extensions, whether files are binary or text-based, and which layouts can render them.
+
+## List and read media types
+
+```typescript
+const types = await t4.mediaTypes.list();
+for (const mediaType of types) {
+  console.log(mediaType.name, mediaType.extensions, mediaType.defaultLayout);
+}
+
+const images = await t4.mediaTypes.get(1);
+```
+
+`get()` returns a mutable `MediaType`:
+
+| Property | Type | Mutable | Description |
+|---|---|---|---|
+| `id` | `number` | no | Media type ID |
+| `name` | `string` | yes | Display name, such as `'Image'` |
+| `extensions` | `string[]` | yes | Permitted extensions, such as `['gif', 'jpg', 'jpeg', 'png', 'svg', 'webp']` |
+| `binary` | `boolean` | yes | Whether files are binary rather than text-based |
+| `parseForTags` | `boolean` | yes | Whether T4 parses tags; valid only when `binary` is `false` |
+| `maxSize` | `string \| null` | yes | Formatted maximum size, such as `'5.0 KB'`, or `null` for unlimited |
+| `layouts` | `MediaTypeLayout[]` | yes | Layouts with `name` and `default` |
+| `defaultLayout` | `string` | yes | Default layout name, such as `'image/normal'` |
+
+## Create a media type
+
+```typescript
+const video = await t4.mediaTypes.create({
+  name: 'Video',
+  extensions: ['mp4', 'webm', 'mov'],
+  binary: true,
+  maxSize: '50 MB', // also accepts 52428800 bytes or null for unlimited
+  layouts: [
+    { name: 'video/*', default: false },
+    { name: 'video/looping', default: true },
+  ],
+});
+```
+
+Instead of setting `default: true`, pass `defaultLayout`:
+
+```typescript
+await t4.mediaTypes.create({
+  name: 'Video',
+  extensions: ['mp4', 'webm'],
+  binary: true,
+  layouts: [
+    { name: 'video/*', default: false },
+    { name: 'video/looping', default: false },
+  ],
+  defaultLayout: 'video/looping',
+});
+```
+
+## Update a media type
+
+### Direct update
+
+```typescript
+await t4.mediaTypes.update(1, {
+  name: 'Image Updated',
+  extensions: ['gif', 'jpg', 'jpeg', 'png', 'svg', 'webp', 'avif'],
+  maxSize: '10 MB',
+});
+```
+
+### Mutable item
+
+```typescript
+const mediaType = await t4.mediaTypes.get(1);
+mediaType.name = 'Image Updated';
+mediaType.extensions = [...mediaType.extensions, 'avif'];
+mediaType.maxSize = '10 MB';
+mediaType.defaultLayout = 'image/*';
+await mediaType.save();
+```
+
+## Set the maximum size
+
+`maxSize` accepts:
+
+- A formatted string: `'2 KB'`, `'5 MB'`, or `'512 B'`
+- A number of bytes: `2048` or `5242880`
+- `null` for unlimited size
+
+On read, `maxSize` is a formatted string or `null`.
+
+## Validation rules
+
+1. `parseForTags` cannot be `true` when `binary` is `true`. Tag parsing applies only to text-based media such as CSS, JavaScript, and PHP.
+2. Every media type requires at least one default layout.
+
+For a non-binary type, enable `parseForTags` to let T4 process tags in the file content:
+
+```typescript
+await t4.mediaTypes.create({
+  name: 'CSS Stylesheet',
+  extensions: ['css'],
+  binary: false,
+  parseForTags: true,
+  layouts: [{ name: 'css/*', default: true }],
+});
+```
+
+---
+
+**Previous:** [Media](./media.md) · **Next:** [Channels](./channels.md)