@terminalfour/terminalfour-js 1.0.0-rc.1

package/LICENSE.md

@@ -0,0 +1,106 @@
+SPDX-License-Identifier: Elastic-2.0
+
+Copyright (c) 2026 Terminalfour Solutions Limited
+
+The licensor for the purposes of the terms below is Terminalfour Solutions
+Limited, a company incorporated in Ireland. The software is terminalfour-js.
+
+The text below is the Elastic License 2.0, reproduced verbatim. It is a
+source-available licence, not an OSI-approved open-source licence.
+
+---
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf of
+your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate these terms
+after such reinstatement, any additional violation of these terms will cause
+your licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,169 @@
+# terminalfour-js
+
+A TypeScript SDK for working with the [Terminalfour](https://www.terminalfour.com/) Platform REST API.
+
+```bash
+npm install terminalfour-js
+```
+
+```typescript
+import { T4Client } from 'terminalfour-js';
+
+const t4 = new T4Client({
+  baseUrl: 'https://mysite.edu/terminalfour/rs',
+  apiToken: 'your-api-token',
+});
+```
+
+## Why use terminalfour-js?
+
+The Terminalfour REST API is powerful but verbose. Updating content can require more than five requests, negative random IDs, data merged from multiple endpoints, and element keys such as `"Title#2:1"`. terminalfour-js handles that API plumbing and lets you work with field names and typed values.
+
+```typescript
+await t4.section(482).content.create({
+  type: 44,
+  name: 'New Article',
+  fields: {
+    Title: 'Breaking News',
+    Category: 'Featured',        // list value by name, not "listId:itemId"
+    'Hero Image': './photo.jpg', // uploads the file automatically
+    'Publish Date': new Date(),  // accepts a Date object
+  },
+});
+```
+
+Retrieve an item, change its fields, and save it:
+
+```typescript
+const article = await t4.section(482).content.get(9132);
+article.fields['Title'] = 'Updated Headline';
+article.status = 'approved';
+await article.save();
+```
+
+Section operations start from a lightweight section reference:
+
+```typescript
+const section = t4.section(482);
+
+await section.content.list();
+await section.subsections();
+await section.publish({ branch: true });
+await section.addSection({ name: 'Child', customFields: { Title: 'Hello' } });
+```
+
+## Requirements
+
+- **Node 18 or later:** The SDK uses the built-in `fetch`, `FormData`, and `Error.cause`.
+- **Server-side execution:** Do not include the SDK or API token in front-end code.
+- **ESM and CommonJS:** Use either `import` or `require`.
+- **TypeScript declarations:** No `@types` package is needed.
+- **Zero runtime dependencies.**
+
+## Keep the API token server-side
+
+Do not use this SDK in front-end code. The `apiToken` has all the privileges of its associated user, and browser bundles are publicly readable. The SDK throws if you construct a client in a browser.
+
+Construct the client in server-side code and return only the data the browser needs. See [Getting Started](./docs/getting-started.md#keep-the-client-server-side) for an example and the full runtime check.
+
+## Supported resources
+
+| Resource | Operations |
+|---|---|
+| **Sections** | get, create, update, delete, purge, move, tree, subsections, channels, owner, metadata, page layouts, edit rights, content types, publish |
+| **Content** | list, get, create, update, delete, purge, move, duplicate, approve, approveAll |
+| **Content Types** | list, get, create, update, delete, add/remove fields, content layouts (CRUD) |
+| **Lists** | list, get, create, update, delete, add/remove items |
+| **Groups** | list, get, create, update, delete, add/remove members |
+| **Users** | list, get, create, update, delete, auth methods, custom fields |
+| **Page Layouts** | list, get, create, update, delete |
+| **Channels** | list, get, publish |
+| **Media** | get, create, update, delete, purge (auto-detects type, handles binary and text) |
+| **Media Categories** | get, create, update, delete, purge, move, list items, subcategories |
+| **Media Library** | full category tree |
+| **Media Types** | list, get, create, update |
+| **Navigation** | list, get, create, update, delete (all 19 core navigation objects) |
+| **Handlebars** | helpers and partials: list, get, create, update, delete, purge |
+| **Platform** | about, database, environment, licence |
+
+The SDK supports every element type: plain text, HTML, dates, select boxes, checkboxes, radio buttons, multi-selects, cascading lists, files, images, media, section/content links, numbers, content owners, group selects, keyword selectors, and repeaters.
+
+## Documentation
+
+Start with [Getting Started](./docs/getting-started.md), then use the resource guides as references:
+
+- [Sections](./docs/sections.md): CRUD, tree navigation, metadata, page layouts, edit rights, and publishing
+- [Content](./docs/content.md): CRUD, move, duplicate, approve, and all element types
+- [Content Types](./docs/content-types.md): types, fields, and content layouts
+- [Lists](./docs/lists.md): list management and item changes
+- [Groups & Users](./docs/groups-and-users.md): CRUD, authentication methods, and memberships
+- [Page Layouts](./docs/page-layouts.md): CRUD with processor and syntax resolution
+- [Media](./docs/media.md): items, categories, library trees, and uploads
+- [Media Types](./docs/media-types.md): definitions, extensions, and layouts
+- [Channels](./docs/channels.md): details and publishing
+- [Navigation](./docs/navigation.md): all navigation object types, including A to Z, Breadcrumbs, and Site Map
+- [Handlebars](./docs/handlebars.md): custom helpers and partials
+- [Error Handling](./docs/error-handling.md): `T4ApiError`, debugging, and cache management
+- [TypeScript Reference](./docs/typescript.md): exported types and interfaces
+
+## More examples
+
+```typescript
+// Bulk approve all pending content
+const totalApprovedCount = await t4.section(482).content.approveAll();
+
+// Duplicate a content item
+const item = await t4.section(482).content.get(9132);
+await item.duplicate();    // same section, auto-named "(1)"
+await item.duplicate(500); // different section, original name
+
+// Move a section
+await t4.section(500).move(233);
+
+// Create a content type with fields
+await t4.contentTypes.create({
+  name: 'Blog Post',
+  elements: [
+    { name: 'Title', type: 'Plain Text', required: true },
+    { name: 'Body', type: 'HTML' },
+    { name: 'Category', type: 'Select Box', listId: 71 },
+  ],
+});
+
+// Upload media
+const media = await t4.media.create({
+  file: './hero-image.jpg',
+  name: 'Hero Image',
+  category: 391,
+});
+
+// Create a Handlebars custom helper
+await t4.handlebars.helpers.create({
+  name: 'truncate',
+  code: `function(context, options) {
+    return context.substring(0, options.hash('len')) + '...';
+}`,
+});
+```
+
+## Contributing
+
+Pull requests are welcome. Before opening one, read `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`.
+
+The SDK has no runtime dependencies, and the tests use a mocked HTTP client. You do not need a T4 instance to contribute:
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+Every change to `src/` should have matching test coverage in `tests/`.
+
+Contributions require a signed [CLA](./CLA.md). Report security issues privately per [SECURITY.md](./SECURITY.md) rather than as a public issue.
+
+## Licence
+
+[Elastic License 2.0](./LICENSE.md).
+
+This project is **open code, not open source**. You can read, use, modify, and distribute the SDK. You cannot offer it to third parties as a hosted or managed service. The Elastic License 2.0 is a source-available licence, not an OSI-approved open-source licence.

package/dist/cjs/element-resolver.d.ts

@@ -0,0 +1,115 @@
+import { HttpClient } from './http-client.js';
+import { TypeRegistry } from './type-registry.js';
+/** A content type element from the template */
+export interface TemplateElement {
+    id: number;
+    name: string;
+    alias: string;
+    type: number;
+    sequence: number;
+    listId: number;
+    maxSize?: number;
+    contentTypeElementConfiguration?: {
+        contentTypeId: number;
+        contentTypeDTO?: {
+            id: number;
+            contentTypeElements: TemplateElement[];
+        };
+        minRepeats: number;
+        maxRepeats: number;
+    };
+}
+/** List item from GET /list/{id}/{language} */
+interface ListItem {
+    id: number;
+    name: string;
+    value: string;
+    listId: number;
+    sublist: number;
+}
+/** List response from GET /list/{id}/{language} */
+interface ListResponse {
+    id: number;
+    items: ListItem[];
+}
+/** Keyword selector AND group */
+interface KeywordAndGroup {
+    and: Array<string>;
+}
+/** Keyword selector input: array of OR items, where each item is a string or AND group */
+export type KeywordSelectorInput = {
+    or: Array<string | KeywordAndGroup>;
+};
+/** Repeater item input from the developer */
+export interface RepeaterInput {
+    name: string;
+    fields: Record<string, unknown>;
+}
+/** Section/Content Link input from the developer */
+export interface SectionContentLinkInput {
+    sectionId: number;
+    contentId?: number;
+    linkText?: string;
+}
+/** Context needed for resolving certain element types (e.g. SS links) */
+export interface ResolveContext {
+    fromSectionId: number;
+    fromContentId: number;
+}
+/** Input for inline media upload within a Media element */
+export interface MediaElementUpload {
+    file: string | Blob | {
+        file: string | Blob;
+        filename?: string;
+    };
+    name: string;
+    category: number;
+    description?: string;
+}
+/** Function that creates a media item and returns its ID */
+export type MediaCreateFn = (data: MediaElementUpload) => Promise<number>;
+/**
+ * Resolves developer-friendly field values to T4 API element format.
+ * Handles list lookups, date conversion, repeater building, etc.
+ */
+export declare class ElementResolver {
+    private readonly httpClient;
+    private readonly typeRegistry;
+    private readonly mediaCreateFn;
+    private listCache;
+    constructor(httpClient: HttpClient, _defaultLanguage: string, typeRegistry: TypeRegistry, mediaCreateFn?: MediaCreateFn | null);
+    /**
+     * Resolves a single field value based on its element type.
+     * Uses the TypeRegistry to look up type names instead of hardcoded IDs.
+     */
+    resolveValue(value: unknown, element: TemplateElement, language: string, allElements?: TemplateElement[], context?: ResolveContext): Promise<unknown>;
+    getList(listId: number, language: string): Promise<ListResponse>;
+    private resolveItemName;
+    private resolveDate;
+    /** Select Box, Radio Button — single list value: "listId:itemId" */
+    private resolveSingleList;
+    /** Checkbox, Multiple Select — "listId:id1,id2" */
+    private resolveCheckbox;
+    /** Multi-Select — "listId:id1;listId:id2" */
+    private resolveMultiSelect;
+    /** Cascading List — "listId1:itemId1, listId2:itemId2" */
+    private resolveCascadingList;
+    /** Group Select — comma-separated group IDs */
+    private resolveGroupSelect;
+    /** Keyword Selector — OR items comma-separated, AND groups with && */
+    private resolveKeywordSelector;
+    /** File/Image — upload file via POST /upload/ and return element value */
+    private resolveFileUpload;
+    /** Section/Content Link — create SS record and return T4 tag */
+    private resolveSectionContentLink;
+    /** Regex to match anchor tags that are SS link markers (have data-section-id attribute) */
+    private static readonly SSLINK_ANCHOR_REGEX;
+    /**
+     * Reverts friendly anchor elements in HTML back to T4 SS link tags.
+     * - Existing links (data-t4-sslink="39") → `<t4 type="sslink" sslink_id="39"/>`
+     * - New links (no data-t4-sslink or data-t4-sslink="new") → creates SS record via PUT /ssl, then inserts the tag
+     */
+    private revertHtmlSsLinks;
+}
+export {};
+//# sourceMappingURL=element-resolver.d.ts.map

package/dist/cjs/element-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-resolver.d.ts","sourceRoot":"","sources":["../../src/element-resolver.ts"],"names":[],"mappings":"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"}