@terminalfour/terminalfour-js 1.0.0-rc.1

package/dist/esm/types.d.ts

@@ -0,0 +1,211 @@
+/** Configuration for the T4Client */
+export interface T4ClientConfig {
+    /**
+     * Base URL of the T4 REST API, e.g. `https://mysite.edu/terminalfour/rs`.
+     * Trailing slashes are stripped. Must be an absolute http/https URL —
+     * https is strongly recommended because the API token is sent as a header.
+     */
+    baseUrl: string;
+    apiToken: string;
+    language?: string;
+    /** Maximum number of concurrent HTTP requests. Defaults to 10. */
+    concurrency?: number;
+}
+/** Optional language override for per-call language selection */
+export interface LanguageOption {
+    language?: string;
+}
+/** Raw content data transfer object from the T4 API */
+export interface ContentDTO {
+    id: number;
+    contentTypeID: number;
+    name: string;
+    language: string;
+    status: number;
+    elements: Record<string, unknown>;
+    version: number;
+    owner: {
+        id: number;
+        type: string;
+    };
+    channels: number[];
+    sectionIDs?: number[];
+    archiveSection?: number | null;
+    lastModified?: number;
+    lastModifiedBy?: number;
+    lastModifierName?: string;
+    publishDate?: number;
+    expiryDate?: number;
+    reviewDate?: number;
+}
+/** Raw section shape from the T4 API */
+export interface ApiSectionDTO {
+    id: number;
+    name: string;
+    parent: number | null;
+    show?: boolean;
+    status?: number;
+    path?: string;
+    pathMembers?: number[];
+    lastModified?: number;
+    'output-uri'?: string;
+    'file-name'?: string;
+    archive?: boolean;
+    channels?: Array<{
+        id: number;
+        pageLayout: number;
+        inheritedPageLayout: number;
+    }>;
+    inheritedPageLayouts?: Record<string, number>;
+    accessControl?: {
+        id: number;
+        type: number;
+        enabled: boolean;
+        active: boolean;
+    };
+    metaData?: {
+        id: number;
+        type: number;
+        enabled: boolean;
+        active: boolean;
+    };
+    metaDatas?: Array<{
+        id: number;
+        value: string;
+        lang: string;
+    }>;
+    userIDs?: number[];
+    inheritedUserIDs?: number[];
+    groupIDs?: number[];
+    inheritedGroupIDs?: number[];
+    contentTypeScopes?: Array<{
+        id: number;
+        scope: number;
+        inherited: boolean;
+    }>;
+    [key: string]: unknown;
+}
+/** Content type definition */
+export interface ContentTypeData {
+    id: number;
+    name: string;
+    description: string;
+    minUserLevel: string;
+    workflow: number;
+    sharedGroups: number[];
+    primaryGroup: number;
+    directEdit: boolean;
+    fields: Record<string, ContentTypeFieldDef>;
+}
+/** Field definition within a content type */
+export interface ContentTypeFieldDef {
+    name: string;
+    description: string;
+    type: string;
+    required: boolean;
+    maxSize: number;
+    listId: number;
+    listName: string;
+    shown: boolean;
+    useAsFilename: boolean;
+    /** HTML editor name. Only present on HTML elements with an explicit editor configured. Set to `null` to remove. */
+    editor?: string | null;
+    config?: {
+        contentTypeId: number;
+        contentTypeName: string;
+        contentTypeDescription: string;
+        layout: string;
+        minRepeats: number;
+        maxRepeats: number;
+    };
+}
+/** A node in the site hierarchy tree */
+export interface HierarchyNode {
+    id: number;
+    name: string;
+    parentId: number | null;
+    children?: HierarchyNode[];
+}
+/** Options for retrieving the hierarchy tree */
+export interface GetTreeOptions extends LanguageOption {
+    depth?: number;
+}
+/** Data required to add a new section */
+export interface AddSectionData {
+    name: string;
+    parentId: number;
+    /** Whether the section appears in navigation on the published site. Defaults to true. */
+    show?: boolean;
+    /** Section status: 'approved' | 'pending' | 'inactive'. Defaults to 'approved'. */
+    status?: 'approved' | 'pending' | 'inactive';
+    /** Optional custom fields for the section (e.g. { Title: "My Section Title" }). */
+    customFields?: Record<string, unknown>;
+}
+/** A channel associated with a section (lightweight — just id and name) */
+export interface SectionChannel {
+    id: number;
+    name: string;
+}
+/** Owner information for a section or content item */
+export interface Owner {
+    id: number;
+    /** User level: 'admin', 'power-user', 'moderator', 'contributor', or 'visitor' */
+    type: string;
+    username: string;
+    firstName: string;
+    lastName: string;
+    emailAddress: string;
+}
+/** Accepted date input: Date object, timestamp in ms, or date string */
+export type DateInput = Date | number | string;
+/** Data required to create new content */
+export interface CreateContentData {
+    type: number;
+    name: string;
+    fields: Record<string, unknown>;
+    /** Content status: 'draft' | 'pending' | 'approved' | 'inactive'. Defaults to 'pending'. */
+    status?: 'draft' | 'pending' | 'approved' | 'inactive';
+    /** Publish date. Accepts Date, timestamp (ms), or date string. */
+    publishDate?: DateInput;
+    /** Expiry date. Accepts Date, timestamp (ms), or date string. */
+    expiryDate?: DateInput;
+    /** Review date. Accepts Date, timestamp (ms), or date string. */
+    reviewDate?: DateInput;
+    /** Section ID where expired content is archived. */
+    archiveSection?: number;
+    /** Content owner user ID. Defaults to 0 (current user). */
+    owner?: number;
+}
+/** Data required to update existing content */
+export interface UpdateContentData {
+    /** Updated content name. If omitted, keeps existing name. */
+    name?: string;
+    /** Updated fields. Only fields provided are changed; others keep existing values. */
+    fields?: Record<string, unknown>;
+    /** Updated status. If omitted, defaults to 'pending'. */
+    status?: 'draft' | 'pending' | 'approved' | 'inactive';
+    /** Publish date. Accepts Date, timestamp (ms), or date string. Pass null to clear. */
+    publishDate?: DateInput | null;
+    /** Expiry date. Accepts Date, timestamp (ms), or date string. Pass null to clear. */
+    expiryDate?: DateInput | null;
+    /** Review date. Accepts Date, timestamp (ms), or date string. Pass null to clear. */
+    reviewDate?: DateInput | null;
+    /** Section ID where expired content is archived. Pass null to clear. */
+    archiveSection?: number | null;
+    /** Content owner user ID. */
+    owner?: number;
+}
+/** Data required to move content to another section */
+export interface MoveContentData {
+    sectionId: number;
+}
+/** Options for an HTTP request made by the internal HttpClient */
+export interface HttpRequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'MOVE' | 'APPROVE' | 'COPY';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    multipart?: boolean;
+    formData?: FormData;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/types.d.ts.map

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

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/esm/utils.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Resolves the effective language for an API request.
+ *
+ * Resolution order:
+ * 1. Explicit per-call override
+ * 2. Client-level default language
+ * 3. Hardcoded fallback "en"
+ */
+export declare function resolveLanguage(override?: string, defaultLang?: string): string;
+/**
+ * Converts a DateInput (Date, timestamp in ms, or date string) to a
+ * millisecond timestamp suitable for the T4 API.
+ * Returns null if the input is null or undefined.
+ */
+export declare function toTimestamp(value: Date | number | string | null | undefined): number | null;
+/**
+ * Decodes HTML entities in a string.
+ * Handles named entities (&, », etc.) and numeric/hex entities (/, ').
+ */
+export declare function decodeHtmlEntities(str: string): string;
+/**
+ * Formats a byte count into a human-readable string.
+ * Examples: "0 B", "512 B", "15.0 KB", "5.0 MB"
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Parses a human-readable file size string into bytes.
+ * Accepts: '2 KB', '5.0 MB', '512 B', '1024', etc.
+ * Returns 0 for invalid/unparseable input.
+ */
+export declare function parseFileSize(input: string | number | null | undefined): number;
+/**
+ * Parses a T4 element key like "Title#2:1" into its parts.
+ * Returns null if the key doesn't match the expected format.
+ */
+export declare function parseElementKey(key: string): {
+    name: string;
+    elementId: number;
+    type: number;
+} | null;
+/**
+ * Maps T4 status codes to friendly strings.
+ * Sections use 0–2; content and media also use 3 (draft).
+ */
+export declare const STATUS_MAP: Record<number, string>;
+/**
+ * Converts a numeric T4 status code to a friendly string.
+ */
+export declare function mapStatus(code: number): string;
+/**
+ * Maps friendly status strings to T4 numeric status codes.
+ * Sections use 0–2; content also uses 3 (draft).
+ */
+export declare const STATUS_CODES: Record<string, number>;
+/**
+ * Maps T4 auth level codes to friendly user level strings.
+ */
+export declare const AUTH_LEVEL_MAP: Record<number, string>;
+/**
+ * Maps friendly user level strings to T4 auth level codes.
+ */
+export declare const AUTH_LEVEL_REVERSE: Record<string, number>;
+/**
+ * Recursively flattens a hierarchical group tree into a flat Map of id → name.
+ */
+export declare function flattenGroups(groups: Array<{
+    id: number;
+    name: string;
+    groupChildren?: unknown[];
+}>, map?: Map<number, string>): Map<number, string>;
+/** 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;
+    filename?: string;
+};
+/**
+ * Resolves a file input (path, URL, Blob, or ReadableStream) to a Blob.
+ */
+export declare function resolveFileToBlob(file: string | Blob | NodeJS.ReadableStream): Promise<Blob>;
+/**
+ * Derives a filename from a file input (path, URL, Blob, ReadableStream, or { file, filename }).
+ */
+export declare function deriveFilename(input: FileInput): string;
+/**
+ * Logs a warning message when T4_DEBUG=1 is set.
+ * Used for graceful degradation paths where errors are caught and fallback
+ * values are returned — the warning makes these visible during debugging.
+ */
+export declare function debugWarn(message: string, error?: unknown): void;
+/**
+ * Throws when running in a browser.
+ *
+ * The T4 API token is a full-privilege credential sent on every request. Bundling
+ * it into front-end code exposes it to anyone who opens devtools, so the SDK fails
+ * loudly at construction time — during development, when it's cheapest to fix —
+ * rather than silently shipping a leaked credential to production.
+ *
+ * There is no override. Detection deliberately requires both `window` and
+ * `window.document`, so genuine server-side runtimes without a DOM (Node, Deno,
+ * Bun, Cloudflare Workers) are unaffected.
+ */
+export declare function assertNotBrowser(): void;
+/**
+ * Validates and normalises a base URL.
+ *
+ * - Throws if the value isn't a parseable absolute URL or doesn't use http/https.
+ * - Warns when the scheme is `http:`, because every request sends the API token
+ *   in an `Authorization` header and plain HTTP transmits it in cleartext.
+ * - Strips trailing slashes so `baseUrl + path` never produces a double slash.
+ */
+export declare function normaliseBaseUrl(baseUrl: string): string;
+/** Default cache TTL in milliseconds (5 minutes) */
+export declare const DEFAULT_CACHE_TTL: number;
+/** Returns the current cache epoch. */
+export declare function getCacheEpoch(): number;
+/**
+ * Bumps the global cache epoch, causing all TTL-based caches to miss
+ * on their next read. This is the mechanism behind `T4Client.clearCache()`.
+ */
+export declare function invalidateAllCaches(): void;
+/**
+ * A Map with time-to-live expiration on entries.
+ * Entries are lazily evicted on access — expired entries return undefined.
+ * Respects the global cache epoch: entries written before an epoch bump are stale.
+ */
+export declare class TtlMap<K, V> {
+    private readonly entries;
+    private readonly ttl;
+    constructor(ttl?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    clear(): void;
+}
+/**
+ * A single-value cache with TTL expiration.
+ * Stores a promise that resolves to the cached value.
+ * Respects the global cache epoch: entries written before an epoch bump are stale.
+ */
+export declare class TtlValue<V> {
+    private entry;
+    private readonly ttl;
+    constructor(ttl?: number);
+    get(): V | undefined;
+    set(value: V): void;
+    clear(): void;
+}
+//# sourceMappingURL=utils.d.ts.map

package/dist/esm/utils.d.ts.map

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