@terminalfour/terminalfour-js 1.0.0-rc.1

package/dist/esm/utils.js

@@ -0,0 +1,355 @@
+/**
+ * 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 function resolveLanguage(override, defaultLang) {
+    return override ?? defaultLang ?? 'en';
+}
+/**
+ * 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 function toTimestamp(value) {
+    if (value == null)
+        return null;
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string') {
+        const ts = new Date(value).getTime();
+        return isNaN(ts) ? null : ts;
+    }
+    return null;
+}
+const HTML_ENTITIES = {
+    '&': '&',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&#x27;': "'",
+    '&#x2F;': '/',
+    '&#39;': "'",
+    '&#47;': '/',
+    '&apos;': "'",
+    '&raquo;': '»',
+};
+const ENTITY_RE = /&#x[0-9a-fA-F]+;|&#\d+;|&\w+;/g;
+/**
+ * Decodes HTML entities in a string.
+ * Handles named entities (&amp;, &raquo;, etc.) and numeric/hex entities (&#x2F;, &#39;).
+ */
+export function decodeHtmlEntities(str) {
+    return str.replace(ENTITY_RE, (match) => {
+        if (HTML_ENTITIES[match])
+            return HTML_ENTITIES[match];
+        // Hex entity: &#xHH;
+        if (match.startsWith('&#x')) {
+            const code = parseInt(match.slice(3, -1), 16);
+            return isNaN(code) ? match : String.fromCharCode(code);
+        }
+        // Decimal entity: &#DD;
+        if (match.startsWith('&#')) {
+            const code = parseInt(match.slice(2, -1), 10);
+            return isNaN(code) ? match : String.fromCharCode(code);
+        }
+        return match;
+    });
+}
+/**
+ * Formats a byte count into a human-readable string.
+ * Examples: "0 B", "512 B", "15.0 KB", "5.0 MB"
+ */
+export function formatFileSize(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * 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 function parseFileSize(input) {
+    if (input == null)
+        return 0;
+    if (typeof input === 'number')
+        return input;
+    const trimmed = input.trim().toLowerCase();
+    if (!trimmed)
+        return 0;
+    const match = trimmed.match(/^([\d.]+)\s*(b|kb|mb|gb)?$/i);
+    if (!match)
+        return 0;
+    const value = parseFloat(match[1]);
+    if (isNaN(value))
+        return 0;
+    const unit = (match[2] || 'b').toLowerCase();
+    switch (unit) {
+        case 'b': return Math.round(value);
+        case 'kb': return Math.round(value * 1024);
+        case 'mb': return Math.round(value * 1024 * 1024);
+        case 'gb': return Math.round(value * 1024 * 1024 * 1024);
+        default: return Math.round(value);
+    }
+}
+/**
+ * Parses a T4 element key like "Title#2:1" into its parts.
+ * Returns null if the key doesn't match the expected format.
+ */
+export function parseElementKey(key) {
+    const match = key.match(/^(.+)#(\d+):(\d+)$/);
+    if (!match)
+        return null;
+    return { name: match[1], elementId: parseInt(match[2], 10), type: parseInt(match[3], 10) };
+}
+/**
+ * Maps T4 status codes to friendly strings.
+ * Sections use 0–2; content and media also use 3 (draft).
+ */
+export const STATUS_MAP = {
+    0: 'approved',
+    1: 'pending',
+    2: 'inactive',
+    3: 'draft',
+};
+/**
+ * Converts a numeric T4 status code to a friendly string.
+ */
+export function mapStatus(code) {
+    return STATUS_MAP[code] ?? `unknown (${code})`;
+}
+/**
+ * Maps friendly status strings to T4 numeric status codes.
+ * Sections use 0–2; content also uses 3 (draft).
+ */
+export const STATUS_CODES = {
+    approved: 0,
+    pending: 1,
+    inactive: 2,
+    draft: 3,
+};
+/**
+ * Maps T4 auth level codes to friendly user level strings.
+ */
+export const AUTH_LEVEL_MAP = {
+    0: 'admin',
+    40: 'power-user',
+    1: 'moderator',
+    2: 'contributor',
+    50: 'visitor',
+};
+/**
+ * Maps friendly user level strings to T4 auth level codes.
+ */
+export const AUTH_LEVEL_REVERSE = {
+    'admin': 0,
+    'power-user': 40,
+    'moderator': 1,
+    'contributor': 2,
+    'visitor': 50,
+};
+/**
+ * Recursively flattens a hierarchical group tree into a flat Map of id → name.
+ */
+export function flattenGroups(groups, map = new Map()) {
+    for (const g of groups) {
+        map.set(g.id, g.name);
+        if (Array.isArray(g.groupChildren) && g.groupChildren.length > 0) {
+            flattenGroups(g.groupChildren, map);
+        }
+    }
+    return map;
+}
+/**
+ * Resolves a file input (path, URL, Blob, or ReadableStream) to a Blob.
+ */
+export async function resolveFileToBlob(file) {
+    if (file instanceof Blob)
+        return file;
+    if (typeof file === 'string') {
+        if (file.startsWith('https://') || file.startsWith('http://')) {
+            const response = await fetch(file);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch file from ${file}: ${response.status} ${response.statusText}`);
+            }
+            return await response.blob();
+        }
+        const { readFile } = await import('node:fs/promises');
+        const buffer = await readFile(file);
+        return new Blob([buffer]);
+    }
+    // ReadableStream — collect into buffer
+    const chunks = [];
+    for await (const chunk of file) {
+        chunks.push(new Uint8Array(chunk));
+    }
+    return new Blob(chunks);
+}
+/**
+ * Derives a filename from a file input (path, URL, Blob, ReadableStream, or { file, filename }).
+ */
+export function deriveFilename(input) {
+    if (typeof input === 'string') {
+        if (input.startsWith('https://') || input.startsWith('http://')) {
+            try {
+                return new URL(input).pathname.split('/').pop() || 'file';
+            }
+            catch {
+                return 'file';
+            }
+        }
+        return input.replace(/\\/g, '/').split('/').pop() || 'file';
+    }
+    if (input instanceof Blob)
+        return 'file';
+    if (typeof input === 'object' && input !== null && 'file' in input) {
+        return input.filename
+            || (typeof input.file === 'string' ? deriveFilename(input.file) : 'file');
+    }
+    // ReadableStream — no filename derivable
+    return 'file';
+}
+/**
+ * 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 function debugWarn(message, error) {
+    if (typeof process !== 'undefined' && process.env?.T4_DEBUG === '1') {
+        const detail = error instanceof Error ? error.message : error ? String(error) : '';
+        console.warn(`[T4 SDK] ${message}${detail ? `: ${detail}` : ''}`);
+    }
+}
+/**
+ * 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 function assertNotBrowser() {
+    const isBrowser = typeof window !== 'undefined'
+        && typeof window.document !== 'undefined';
+    if (!isBrowser)
+        return;
+    throw new Error('T4Client cannot be used in a browser. The apiToken is a full-privilege ' +
+        'credential and anything in front-end code is publicly readable, so this would ' +
+        'expose it to every visitor.\n\n' +
+        'Call the T4 API from a server you control (an API route, serverless function, ' +
+        'or backend service) and have the browser talk to that instead.');
+}
+/**
+ * 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 function normaliseBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`T4Client baseUrl "${baseUrl}" is not a valid absolute URL. ` +
+            'Expected something like "https://mysite.edu/terminalfour/rs".');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new Error(`T4Client baseUrl must use http or https, received "${parsed.protocol}".`);
+    }
+    if (parsed.protocol === 'http:') {
+        console.warn('[T4 SDK] baseUrl uses http:// — the API token will be sent in cleartext. ' +
+            'Use https:// unless you are testing against a local instance.');
+    }
+    return baseUrl.replace(/\/+$/, '');
+}
+/** Default cache TTL in milliseconds (5 minutes) */
+export const DEFAULT_CACHE_TTL = 5 * 60 * 1000;
+/**
+ * Global cache epoch. Incremented by `invalidateAllCaches()` to force
+ * all TTL-based caches to treat their entries as expired. Every cache
+ * records the epoch at write time; on read, if the current epoch is
+ * higher, the entry is stale regardless of its TTL.
+ */
+let cacheEpoch = 0;
+/** Returns the current cache epoch. */
+export function getCacheEpoch() {
+    return cacheEpoch;
+}
+/**
+ * Bumps the global cache epoch, causing all TTL-based caches to miss
+ * on their next read. This is the mechanism behind `T4Client.clearCache()`.
+ */
+export function invalidateAllCaches() {
+    cacheEpoch++;
+}
+/**
+ * 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 class TtlMap {
+    constructor(ttl = DEFAULT_CACHE_TTL) {
+        this.entries = new Map();
+        this.ttl = ttl;
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.epoch < cacheEpoch || Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        this.entries.set(key, { value, expiresAt: Date.now() + this.ttl, epoch: cacheEpoch });
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+/**
+ * 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 class TtlValue {
+    constructor(ttl = DEFAULT_CACHE_TTL) {
+        this.entry = null;
+        this.ttl = ttl;
+    }
+    get() {
+        if (!this.entry)
+            return undefined;
+        if (this.entry.epoch < cacheEpoch || Date.now() > this.entry.expiresAt) {
+            this.entry = null;
+            return undefined;
+        }
+        return this.entry.value;
+    }
+    set(value) {
+        this.entry = { value, expiresAt: Date.now() + this.ttl, epoch: cacheEpoch };
+    }
+    clear() {
+        this.entry = null;
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,QAAiB,EAAE,WAAoB;IACrE,OAAO,QAAQ,IAAI,WAAW,IAAI,IAAI,CAAC;AACzC,CAAC;AAGD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAgD;IAC1E,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAGD,MAAM,aAAa,GAA2B;IAC5C,OAAO,EAAE,GAAG;IACZ,MAAM,EAAE,GAAG;IACX,MAAM,EAAE,GAAG;IACX,QAAQ,EAAE,GAAG;IACb,QAAQ,EAAE,GAAG;IACb,QAAQ,EAAE,GAAG;IACb,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,SAAS,EAAE,GAAG;CACf,CAAC;AAEF,MAAM,SAAS,GAAG,gCAAgC,CAAC;AAEnD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,OAAO,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;QACtC,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;QACtD,qBAAqB;QACrB,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9C,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACzD,CAAC;QACD,wBAAwB;QACxB,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9C,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC;AAGD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9B,IAAI,KAAK,GAAG,IAAI;QAAE,OAAO,GAAG,KAAK,IAAI,CAAC;IACtC,IAAI,KAAK,GAAG,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,OAAO,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyC;IACrE,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC;IAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,OAAO,CAAC,CAAC;IAEvB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAC3D,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IAErB,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAE3B,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC7C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACnC,KAAK,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;QAC3C,KAAK,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;QAClD,KAAK,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;QACzD,OAAO,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;AACH,CAAC;AAGD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AAC7F,CAAC;AAGD;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAA2B;IAChD,CAAC,EAAE,UAAU;IACb,CAAC,EAAE,SAAS;IACZ,CAAC,EAAE,UAAU;IACb,CAAC,EAAE,OAAO;CACX,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,YAAY,IAAI,GAAG,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAA2B;IAClD,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,CAAC;IACX,KAAK,EAAE,CAAC;CACT,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAA2B;IACpD,CAAC,EAAE,OAAO;IACV,EAAE,EAAE,YAAY;IAChB,CAAC,EAAE,WAAW;IACd,CAAC,EAAE,aAAa;IAChB,EAAE,EAAE,SAAS;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,OAAO,EAAE,CAAC;IACV,YAAY,EAAE,EAAE;IAChB,WAAW,EAAE,CAAC;IACd,aAAa,EAAE,CAAC;IAChB,SAAS,EAAE,EAAE;CACd,CAAC;AAGF;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAsE,EACtE,MAA2B,IAAI,GAAG,EAAE;IAEpC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjE,aAAa,CAAC,CAAC,CAAC,aAA+E,EAAE,GAAG,CAAC,CAAC;QACxG,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAMD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAA2C;IACjF,IAAI,IAAI,YAAY,IAAI;QAAE,OAAO,IAAI,CAAC;IAEtC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,KAAK,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YAClG,CAAC;YACD,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC/B,CAAC;QAED,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,uCAAuC;IACvC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAA6B,EAAE,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,IAAI,CAAC,MAAoB,CAAC,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAChE,IAAI,CAAC;gBAAC,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC;gBAAC,OAAO,MAAM,CAAC;YAAC,CAAC;QAC7F,CAAC;QACD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC;IAC9D,CAAC;IACD,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,MAAM,CAAC;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QACnE,OAAQ,KAA4E,CAAC,QAAQ;eACxF,CAAC,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9E,CAAC;IACD,yCAAyC;IACzC,OAAO,MAAM,CAAC;AAChB,CAAC;AAGD;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,KAAe;IACxD,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,QAAQ,KAAK,GAAG,EAAE,CAAC;QACpE,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,OAAO,CAAC,IAAI,CAAC,YAAY,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAGD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,WAAW;WAC1C,OAAQ,MAAiC,CAAC,QAAQ,KAAK,WAAW,CAAC;IAExE,IAAI,CAAC,SAAS;QAAE,OAAO;IAEvB,MAAM,IAAI,KAAK,CACb,yEAAyE;QACzE,gFAAgF;QAChF,iCAAiC;QACjC,gFAAgF;QAChF,gEAAgE,CACjE,CAAC;AACJ,CAAC;AAGD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,qBAAqB,OAAO,iCAAiC;YAC7D,+DAA+D,CAChE,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,sDAAsD,MAAM,CAAC,QAAQ,IAAI,CAC1E,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CACV,2EAA2E;YAC3E,+DAA+D,CAChE,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACrC,CAAC;AAGD,oDAAoD;AACpD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAE/C;;;;;GAKG;AACH,IAAI,UAAU,GAAG,CAAC,CAAC;AAEnB,uCAAuC;AACvC,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,UAAU,EAAE,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,MAAM;IAIjB,YAAY,MAAc,iBAAiB;QAH1B,YAAO,GAAG,IAAI,GAAG,EAAqD,CAAC;QAItF,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,GAAG,CAAC,GAAM;QACR,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,KAAK,CAAC,KAAK,GAAG,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC7D,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAM,EAAE,KAAQ;QAClB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,QAAQ;IAInB,YAAY,MAAc,iBAAiB;QAHnC,UAAK,GAA0D,IAAI,CAAC;QAI1E,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,GAAG;QACD,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAClC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;YACvE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED,GAAG,CAAC,KAAQ;QACV,IAAI,CAAC,KAAK,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAC9E,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;CACF"}

package/docs/channels.md

@@ -0,0 +1,62 @@
+# Channels
+
+Use `t4.channels` to list channel summaries, inspect channel configuration, and publish a channel.
+
+## List channels
+
+```typescript
+const channels = await t4.channels.list();
+// [{ id: 1, name: 'Sample Site', description: '...', rootSectionId: 233 }]
+```
+
+A channel with microsites includes a `microSites` array. The property is omitted when the channel has no microsites.
+
+```typescript
+const channel = channels.find(item => item.microSites);
+if (channel?.microSites) {
+  for (const microsite of channel.microSites) {
+    console.log(microsite.id, microsite.name, microsite.rootSectionId, microsite.parentId);
+  }
+}
+```
+
+## Get channel details
+
+```typescript
+const channel = await t4.channels.get(1);
+```
+
+| Property | Example or meaning |
+|---|---|
+| `name` | `'Sample Site'` |
+| `description` | Channel description |
+| `defaultLayout` | `'text/html'` |
+| `defaultLanguage` | `'en'` |
+| `rootSectionId` | `233` |
+| `fileOutputPath` | `'/web/stage/htdocs/'` |
+| `indexFileName` | `'index.php'` |
+| `baseHref` | `'https://example.com'` |
+| `siteRoot` | `'/'` |
+| `publishUrl` | `'https://example.com'` |
+| `defaultFullTextLayout` | Default fulltext layout |
+| `fullTextExtension` | Fulltext file extension |
+| `fileExtensions` | `['php', 'xml', 'json']`, sorted by priority |
+| `languages` | `[{ code: 'en', name: 'English', charset: 'ISO-8859-15' }]` |
+| `microSites` | `[{ id: 6, name: 'Microsite Test' }]` or `undefined` |
+
+## Publish a channel
+
+```typescript
+const channel = await t4.channels.get(1);
+await channel.publish();
+
+await channel.publish({
+  includeArchives: true,
+  overridePublishPeriodRestriction: true,
+  language: 'fr',
+});
+```
+
+---
+
+**Previous:** [Media Types](./media-types.md) · **Next:** [Navigation](./navigation.md)