@meshmakers/octo-services 3.5.100 → 3.5.110

package/fesm2022/meshmakers-octo-services.mjs

@@ -7,8 +7,8 @@ import { CombinedGraphQLErrors } from '@apollo/client';
 import * as i1 from 'apollo-angular';
 import { gql } from 'apollo-angular';
 import { map, catchError, finalize } from 'rxjs/operators';
-import { of, firstValueFrom, map as map$1, Subject, throwError, from, filter } from 'rxjs';
-import { HttpClient, HttpParams, HttpErrorResponse, HttpContext, HttpHeaders } from '@angular/common/http';
+import { of, firstValueFrom, map as map$1, Subject, throwError, from, switchMap, takeUntil, filter, fromEvent } from 'rxjs';
+import { HttpClient, HttpParams, HttpErrorResponse, HttpContext, HttpHeaders, HttpEventType } from '@angular/common/http';
 import { Upload } from 'tus-js-client';
 import { AuthorizeService } from '@meshmakers/shared-auth';
 
@@ -6592,6 +6592,626 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.5", ngImpor
                 }]
         }] });
 
+/** Thrown when a reference can be turned into no download URL (no `downloadUri`, no `binaryId`, or no tenant). */
+class BinaryDownloadUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BinaryDownloadUnavailableError';
+    }
+}
+const DEFAULT_FILE_NAME = 'download';
+/**
+ * Reads the file name from a `Content-Disposition` header (RFC 6266). The RFC 5987 form
+ * `filename*=UTF-8''…` wins over the plain `filename=` parameter, as browsers do.
+ * Returns `null` when the header is absent or names no file.
+ *
+ * Note: a cross-origin response exposes `Content-Disposition` to script only when the server lists
+ * it in `Access-Control-Expose-Headers`; otherwise this sees `null` and the caller's fallback applies.
+ */
+function parseContentDispositionFileName(header) {
+    if (!header) {
+        return null;
+    }
+    const extended = /filename\*\s*=\s*([^;]+)/i.exec(header);
+    if (extended) {
+        const raw = extended[1].trim().replace(/^"(.*)"$/, '$1');
+        // charset'language'percent-encoded-value
+        const parts = /^([^']*)'[^']*'(.*)$/.exec(raw);
+        const encoded = parts ? parts[2] : raw;
+        try {
+            const decoded = decodeURIComponent(encoded);
+            const name = decoded ? sanitizeFileName(decoded) : null;
+            if (name) {
+                return name;
+            }
+        }
+        catch {
+            // Malformed percent-encoding: fall through to the plain parameter.
+        }
+    }
+    const plain = /(?:^|;)\s*filename\s*=\s*("((?:[^"\\]|\\.)*)"|[^;]+)/i.exec(header);
+    if (plain) {
+        const value = plain[2] !== undefined ? plain[2].replace(/\\(.)/g, '$1') : plain[1].trim();
+        if (value) {
+            return sanitizeFileName(value);
+        }
+    }
+    return null;
+}
+/**
+ * Strips any path a server might send along with the name; the browser would refuse it anyway. An empty name,
+ * `.` or `..` is no file name: `null`, so the caller falls back to the reference's own name.
+ */
+function sanitizeFileName(name) {
+    const base = (name.split(/[\\/]/).pop() ?? name).trim();
+    return base === '' || base === '.' || base === '..' ? null : base;
+}
+/**
+ * Authenticated file downloads for the browser (AB#6171 decision D9).
+ *
+ * Binaries live behind the asset repository's `GET {tenant}/v1/largeBinaries`, which needs a bearer
+ * token with an API scope. Opening the URL in a new tab (`window.open`) sends no token — the service
+ * then signs the tab in through its own login without that scope and answers 403 (AB#5268), and a
+ * popup blocker may swallow the tab anyway because the click is over by the time a URL is known.
+ *
+ * This service therefore fetches the file through `HttpClient`, so the host's `authorizeInterceptor`
+ * attaches the bearer (it covers every URL under the configured service URIs, i.e.
+ * `config.assetServices`), receives a `Blob`, and saves it through a temporary anchor under the real
+ * file name — from `Content-Disposition` when the server sends one, else from the binary's stored
+ * file name. It is owner-agnostic: any `BINARY_LINKED` value works, whichever CK type holds it.
+ *
+ * @example
+ * ```typescript
+ * const downloads = inject(FileDownloadService);
+ * // generic attribute value { binaryId, filename, contentType, size }
+ * await downloads.downloadBinary(attributeValue);
+ * // any authenticated URL
+ * await downloads.downloadUrl(`${assetServices}${tenantId}/v1/files/Files/Reports/report.pdf`, 'report.pdf');
+ * ```
+ */
+class FileDownloadService {
+    httpClient = inject(HttpClient);
+    configurationService = inject(CONFIGURATION_SERVICE, { optional: true });
+    tenantIdProvider = inject(TENANT_ID_PROVIDER, { optional: true });
+    /**
+     * Builds the asset repository download URL for a large binary:
+     * `{assetServices}{tenantId}/v1/largeBinaries?largeBinaryId={binaryId}`.
+     * Returns `null` when the asset service URL or the tenant is unknown.
+     */
+    async buildLargeBinaryUri(binaryId, tenantId) {
+        const assetServices = this.configurationService?.config?.assetServices;
+        const tenant = tenantId ?? (this.tenantIdProvider ? await this.tenantIdProvider() : null);
+        if (!assetServices || !tenant) {
+            return null;
+        }
+        const base = assetServices.endsWith('/') ? assetServices : `${assetServices}/`;
+        return `${base}${encodeURIComponent(tenant)}/v1/largeBinaries?largeBinaryId=${encodeURIComponent(binaryId)}`;
+    }
+    /**
+     * Downloads a binary reference (a `BINARY_LINKED` value or `LargeBinaryInfo`) with the user's
+     * bearer token and saves it. Uses `downloadUri` when present, else builds the URL from `binaryId`.
+     *
+     * @throws BinaryDownloadUnavailableError when no download URL can be determined.
+     * @throws HttpErrorResponse when the server refuses or fails the download.
+     */
+    async downloadBinary(reference, options) {
+        let url = reference.downloadUri || null;
+        if (!url && reference.binaryId) {
+            url = await this.buildLargeBinaryUri(reference.binaryId, options?.tenantId);
+        }
+        if (!url) {
+            throw new BinaryDownloadUnavailableError(reference.binaryId
+                ? 'Cannot build a download URL: asset service URL or tenant unknown'
+                : 'The binary reference carries neither downloadUri nor binaryId');
+        }
+        await this.downloadUrl(url, reference.filename || options?.fallbackFileName, reference.contentType);
+    }
+    /**
+     * Fetches any authenticated URL as a blob and saves it. The file name comes from
+     * `Content-Disposition` when exposed, else from `fallbackFileName`, else `download`.
+     * `context` is passed to the request (see {@link fetchBlob}).
+     */
+    async downloadUrl(url, fallbackFileName, contentType, context) {
+        const response = await this.fetchBlob(url, context);
+        const blob = this.withContentType(response.body ?? new Blob(), contentType);
+        const fileName = parseContentDispositionFileName(response.headers.get('Content-Disposition'))
+            || fallbackFileName
+            || DEFAULT_FILE_NAME;
+        this.saveBlob(blob, fileName);
+    }
+    /**
+     * Fetches an authenticated URL as a blob response, e.g. for an inline preview.
+     * The bearer is attached by the host's `authorizeInterceptor`. `context` lets the caller mark
+     * statuses it handles itself (`MM_CALLER_HANDLED_STATUSES`), so no global error toast shows.
+     */
+    fetchBlob(url, context) {
+        return firstValueFrom(this.httpClient.get(url, { responseType: 'blob', observe: 'response', context }));
+    }
+    /**
+     * Hands a blob to the browser as a file download through a temporary anchor — not `window.open`,
+     * which a popup blocker would swallow once the click is over.
+     */
+    saveBlob(blob, fileName) {
+        const objectUrl = URL.createObjectURL(blob);
+        try {
+            const anchor = document.createElement('a');
+            anchor.href = objectUrl;
+            anchor.download = fileName;
+            anchor.rel = 'noopener';
+            anchor.style.display = 'none';
+            document.body.appendChild(anchor);
+            anchor.click();
+            anchor.remove();
+        }
+        finally {
+            // Safari needs the URL to outlive the click, so it is released on the next macrotask.
+            setTimeout(() => URL.revokeObjectURL(objectUrl));
+        }
+    }
+    /** Re-types a blob the server sent as generic octet-stream when the stored type is more specific. */
+    withContentType(blob, contentType) {
+        if (contentType && (!blob.type || blob.type === 'application/octet-stream') && contentType !== blob.type) {
+            return new Blob([blob], { type: contentType });
+        }
+        return blob;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: FileDownloadService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: FileDownloadService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: FileDownloadService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }] });
+
+/*
+ * Asset-repo file bytes API (epic AB#6171: S2 AB#6174, zip AB#6225; client S13 AB#6230).
+ *
+ * Only the BYTES of files go through REST (`{assetServices}{tenant}/v1/files`); metadata — roots, folder
+ * listings, create folder, rename, move, delete (recursive on the server), linked entities — goes through
+ * the generic tenant GraphQL API against `System.Files` (decision Q1, 2026-10-09).
+ *
+ * | Method | Path | Notes |
+ * |---|---|---|
+ * | GET  | `capabilities` | {@link FilesCapabilities} |
+ * | PUT  | `{root}/{path…}` | raw body upload, `?conflict=fail\|replace\|keepBoth&createFolders=true`; 201 new / 200 replaced |
+ * | GET  | `{root}/{path…}` | download, `?inline=true` for previews |
+ * | POST | `items/{rtId}/content?name=&conflict=` | upload into the folder or root `rtId` |
+ * | PUT  | `items/{rtId}/content` | new content for the existing file `rtId` (rtId and links stay) |
+ * | GET  | `items/{rtId}/content` | download by rtId, `?inline=true` for previews |
+ * | GET  | `stats?root=&path=`, `items/{rtId}/stats` | {@link FolderStats} |
+ * | POST | `zip` | `{ items, rtIds?, fileName? }` → streamed `application/zip` |
+ * | POST | `linked-counts` | `{ rtIds }` (≤ 500) → `{ counts: { rtId: n } }` |
+ *
+ * Path segments are URL-encoded one by one; `root` is the folder root's well-known name. Errors are
+ * problem details `{ status, title, detail, code }` (see {@link parseFilesProblem}).
+ */
+/** Well-known names a folder root cannot use because they are routes of the file API. */
+const FILES_RESERVED_ROOT_NAMES = ['capabilities', 'items', 'linked-counts', 'stats', 'zip'];
+/** How long a "not available" answer of the capabilities is reused before asking again (ms). */
+const FILES_UNAVAILABLE_TTL_MS = 60_000;
+/** Most rtIds one `POST linked-counts` request may carry (server limit). */
+const FILES_LINKED_COUNTS_MAX = 500;
+/** Statuses the callers of this client handle themselves (no global error toast). */
+const CALLER_HANDLED = [400, 403, 404, 409, 413];
+/**
+ * Bytes client of the platform file system (AB#6178, AB#6230): upload with progress (by path, into a
+ * folder by rtId, new content by rtId), download and preview content (by path or rtId) with the user's
+ * bearer under the real file name (decision D9, via {@link FileDownloadService}), the server-side zip,
+ * deep folder statistics and capability detection.
+ *
+ * - The bearer is attached by the host's `authorizeInterceptor` (all URLs under `assetServices`).
+ * - Statuses the caller handles (400, 403, 404, 409, 413) are excluded from the global HTTP error toast
+ *   via `MM_CALLER_HANDLED_STATUSES`; read the reason with {@link parseFilesProblem} and show it where it
+ *   belongs. Blob requests (download, preview, zip) rethrow their error with the parsed problem as body.
+ * - {@link detectCapabilities} asks `GET /capabilities` once per tenant; a 404/405/501 (file API not
+ *   deployed) or 403 (token without the API scope) answers `{ available: false }` silently, so hosts can
+ *   probe safely.
+ * - Downloads, previews and zips are in-memory blobs (D9); respect `previewMaxBytes` / `zipMaxBytes`.
+ *
+ * @example
+ * ```typescript
+ * const files = inject(FilesClientService);
+ * if ((await files.detectCapabilities()).available) {
+ *   files.upload('Files', 'Receipts 2026', file, { conflict: 'keepBoth', createFolders: true }).subscribe(e => …);
+ *   await files.download('Files', 'Receipts 2026/a.pdf');
+ *   const stats = await files.folderStats('Files', 'Receipts 2026');
+ * }
+ * ```
+ */
+class FilesClientService {
+    http = inject(HttpClient);
+    configuration = inject(CONFIGURATION_SERVICE, { optional: true });
+    tenantIdProvider = inject(TENANT_ID_PROVIDER, { optional: true });
+    downloads = inject(FileDownloadService);
+    capabilityCache = new Map();
+    // ---------------------------------------------------------------------------------- capabilities
+    /**
+     * Whether the file API exists for the tenant, plus the server's limits and features. Cached per tenant;
+     * transient failures (network, 5xx) are not cached, so a later call asks again.
+     */
+    async detectCapabilities(tenantId) {
+        const tenant = await this.tenant(tenantId);
+        if (!tenant || !this.configuration?.config?.assetServices) {
+            return { available: false };
+        }
+        let cached = this.capabilityCache.get(tenant);
+        if (!cached) {
+            const answer = this.fetchCapabilities(tenant);
+            cached = { answer, at: Date.now() };
+            this.capabilityCache.set(tenant, cached);
+            answer.catch(() => this.capabilityCache.delete(tenant));
+        }
+        let result;
+        try {
+            result = await cached.answer;
+        }
+        catch {
+            return { available: false };
+        }
+        // "Not available" is kept only briefly: the file API may be deployed or System.Files imported
+        // meanwhile (tenant setup), so a later call after the TTL asks again.
+        if (!result.available && Date.now() - cached.at > FILES_UNAVAILABLE_TTL_MS && this.capabilityCache.get(tenant) === cached) {
+            this.capabilityCache.delete(tenant);
+            return this.detectCapabilities(tenant);
+        }
+        return result;
+    }
+    /** Forgets the detected capabilities (tests, tenant switch). */
+    resetCapabilities() {
+        this.capabilityCache.clear();
+    }
+    // ---------------------------------------------------------------------------------- uploads
+    /**
+     * Uploads one file into a folder addressed by path: `PUT {root}/{folderPath…}/{name}` with progress
+     * events (`reportProgress`). Unsubscribing cancels the request. `conflict` may be a mode (legacy form)
+     * or {@link FilesUploadOptions}. Errors are `HttpErrorResponse` (404 PATH_NOT_FOUND without
+     * `createFolders`, 409 NAME_CONFLICT / AMBIGUOUS_PATH, 413 LIMIT_EXCEEDED, 403 FORBIDDEN).
+     */
+    upload(root, folderPath, file, conflict = {}, tenantId) {
+        const options = typeof conflict === 'string' ? { conflict } : conflict;
+        if (options.name !== undefined && (!options.name || options.name.includes('/'))) {
+            return throwError(() => new FilesPathError(`Invalid file name: ${options.name}`));
+        }
+        let params = new HttpParams().set('conflict', options.conflict ?? 'fail');
+        if (options.createFolders) {
+            params = params.set('createFolders', 'true');
+        }
+        return from(this.itemUrl(root, joinSegments(folderPath, options.name ?? file.name), tenantId)).pipe(switchMap((url) => this.sendUpload('PUT', url, file, params)));
+    }
+    /**
+     * Uploads one file into the folder or root `folderRtId`: `POST items/{rtId}/content?name=&conflict=`.
+     * Same events, cancellation and errors as {@link upload} (409 NOT_A_FOLDER for a file rtId).
+     */
+    uploadToFolder(folderRtId, file, options = {}) {
+        const params = new HttpParams().set('name', options.name ?? file.name).set('conflict', options.conflict ?? 'fail');
+        return from(this.itemContentUrl(folderRtId, options.tenantId)).pipe(switchMap((url) => this.sendUpload('POST', url, file, params)));
+    }
+    /**
+     * Replaces the content of the existing file `fileRtId`: `PUT items/{rtId}/content`. The rtId, the name
+     * and all links stay. Same events and cancellation as {@link upload} (409 NOT_A_FILE for a folder).
+     */
+    replaceContent(fileRtId, file, tenantId) {
+        return from(this.itemContentUrl(fileRtId, tenantId)).pipe(switchMap((url) => this.sendUpload('PUT', url, file, new HttpParams())));
+    }
+    // ---------------------------------------------------------------------------------- downloads
+    /** Downloads a file by path with the user's bearer and saves it under its real name (D9). */
+    async download(root, path, fileName, contentType, tenantId) {
+        const url = await this.itemUrl(root, path, tenantId);
+        await withProblemBody(this.downloads.downloadUrl(url, fileName, contentType, callerHandled()));
+    }
+    /** Downloads a file by rtId (`GET items/{rtId}/content`) and saves it under its real name. */
+    async downloadById(rtId, fileName, contentType, tenantId) {
+        const url = await this.itemContentUrl(rtId, tenantId);
+        await withProblemBody(this.downloads.downloadUrl(url, fileName, contentType, callerHandled()));
+    }
+    /**
+     * Fetches a file's content by path as a blob for an inline preview (`?inline=true`). Inline delivery is
+     * an allow-list on the server (images except SVG, audio, video, PDF, text/plain, CSV, JSON); everything
+     * else stays an attachment with a sandbox CSP. The whole file is held in memory — check
+     * `previewMaxBytes` before previewing large files.
+     */
+    async fetchContent(root, path, tenantId) {
+        return this.fetchBlob(`${await this.itemUrl(root, path, tenantId)}?inline=true`);
+    }
+    /** Fetches a file's content by rtId as a blob for an inline preview (`?inline=true`). */
+    async fetchContentById(rtId, tenantId) {
+        return this.fetchBlob(`${await this.itemContentUrl(rtId, tenantId)}?inline=true`);
+    }
+    /**
+     * Server-side streamed zip (AB#6225) of entries by path and/or rtId; folders are included recursively.
+     * Body `{ items, rtIds?, fileName? }`. Saved under the server's `Content-Disposition` name, else
+     * `fileName`, else `files.zip`. Limits are checked before the first byte (413 LIMIT_EXCEEDED); a
+     * selected entry that is missing or hidden answers 404. The zip is received as an in-memory blob before
+     * it is saved (D9: bearer download, no `window.open`), so the UI must respect `zipMaxBytes`.
+     */
+    async downloadZip(selection, fileName, tenantId) {
+        const { items = [], rtIds = [] } = Array.isArray(selection) ? { items: selection } : selection;
+        const body = { items };
+        if (rtIds.length > 0) {
+            body.rtIds = rtIds;
+        }
+        if (fileName) {
+            body.fileName = fileName;
+        }
+        const url = await this.url(tenantId, 'zip');
+        const response = await withProblemBody(firstValueFrom(this.http.post(url, body, { responseType: 'blob', observe: 'response', context: callerHandled() })));
+        const name = parseContentDispositionFileName(response.headers.get('Content-Disposition')) || fileName || 'files.zip';
+        this.downloads.saveBlob(response.body ?? new Blob(), name);
+    }
+    // ---------------------------------------------------------------------------------- statistics
+    /**
+     * Deep statistics of a root (`path` empty) or folder by path: `GET stats?root=&path=`. Use it instead of
+     * walking the tree on the client (delete confirmation, folder info).
+     */
+    async folderStats(root, path, tenantId) {
+        if (!root) {
+            throw new FilesPathError('Invalid folder: empty root');
+        }
+        let params = new HttpParams().set('root', root);
+        const folderPath = joinSegments(path ?? '');
+        if (folderPath) {
+            params = params.set('path', folderPath);
+        }
+        const url = await this.url(tenantId, 'stats');
+        return normalizeStats(await firstValueFrom(this.http.get(url, { params, context: callerHandled() })));
+    }
+    /**
+     * Deep statistics of a root or folder by rtId: `GET items/{rtId}/stats`. An aborted `signal` cancels
+     * the request (the walk on the server is expensive) and rejects with an `AbortError`.
+     */
+    async folderStatsById(rtId, tenantId, signal) {
+        signal?.throwIfAborted();
+        const url = await this.url(tenantId, 'items', checkRtId(rtId), 'stats');
+        const request = this.http.get(url, { context: callerHandled() });
+        return normalizeStats(await firstValueFrom(signal ? request.pipe(takeUntil(abortOf(signal))) : request, { defaultValue: null })
+            .then((body) => {
+            signal?.throwIfAborted();
+            return body;
+        }));
+    }
+    /**
+     * Links per entry (every association except the folder tree, any role, any direction):
+     * `POST linked-counts { rtIds }` → `{ counts }`. Sends at most {@link FILES_LINKED_COUNTS_MAX} rtIds per
+     * request (more are split). Entries the caller cannot see are omitted from the answer. Only call it
+     * when the capabilities report `linkedCounts`.
+     */
+    async linkedCounts(rtIds, tenantId) {
+        const unique = [...new Set(rtIds.filter((id) => !!id))];
+        const counts = {};
+        if (unique.length === 0) {
+            return counts;
+        }
+        const url = await this.url(tenantId, 'linked-counts');
+        for (let i = 0; i < unique.length; i += FILES_LINKED_COUNTS_MAX) {
+            const chunk = unique.slice(i, i + FILES_LINKED_COUNTS_MAX);
+            const body = await firstValueFrom(this.http.post(url, { rtIds: chunk }, { context: callerHandled() }));
+            Object.assign(counts, body?.counts ?? {});
+        }
+        return counts;
+    }
+    // ---------------------------------------------------------------------------------- URLs
+    /**
+     * `{assetServices}{tenant}/v1/files/{root}/{seg}/…` with every segment URL-encoded.
+     *
+     * @throws FilesPathError for an empty root or a `.` / `..` segment (browsers and proxies resolve
+     *   dot segments even when percent-encoded, so such a URL would address a different resource), and for
+     *   a root named like a route of the file API (`capabilities`, `items`, `stats`, `zip`, case-insensitive).
+     */
+    async itemUrl(root, path, tenantId) {
+        const segments = path.split('/').filter((s) => s.length > 0);
+        if (!root || [root, ...segments].some(isDotSegment)) {
+            throw new FilesPathError(`Invalid file path: ${root}/${path}`);
+        }
+        if (FILES_RESERVED_ROOT_NAMES.includes(root.toLowerCase())) {
+            throw new FilesPathError(`Reserved root name: ${root}`);
+        }
+        return this.url(tenantId, root, ...segments);
+    }
+    /** `{assetServices}{tenant}/v1/files/items/{rtId}/content`. */
+    async itemContentUrl(rtId, tenantId) {
+        return this.url(tenantId, 'items', checkRtId(rtId), 'content');
+    }
+    // ---------------------------------------------------------------------------------- internals
+    sendUpload(method, url, file, params) {
+        return this.http.request(method, url, {
+            body: file,
+            params,
+            headers: { 'Content-Type': file.type || 'application/octet-stream' },
+            reportProgress: true,
+            observe: 'events',
+            context: callerHandled(),
+        }).pipe(filter((event) => event.type === HttpEventType.UploadProgress || event.type === HttpEventType.Response), map$1((event) => {
+            if (event.type === HttpEventType.UploadProgress) {
+                return { type: 'progress', loaded: event.loaded, total: event.total ?? file.size };
+            }
+            return { type: 'done', item: event.body };
+        }));
+    }
+    async fetchBlob(url) {
+        const response = await withProblemBody(this.downloads.fetchBlob(url, callerHandled()));
+        return response.body ?? new Blob();
+    }
+    async fetchCapabilities(tenant) {
+        const url = await this.url(tenant, 'capabilities');
+        try {
+            const body = await firstValueFrom(this.http.get(url, { context: callerHandled([403, 404, 405, 501]) }));
+            return normalizeCapabilities(body);
+        }
+        catch (error) {
+            const status = error?.status;
+            if (status === 403 || status === 404 || status === 405 || status === 501) {
+                return { available: false };
+            }
+            throw error;
+        }
+    }
+    async url(tenantId, ...segments) {
+        // Without both a tenant and the asset service address the URL would point at the wrong resource (a
+        // tenant-less path, or the host origin); fail with a clear client error instead of a misleading 404.
+        const assetServices = this.configuration?.config?.assetServices;
+        if (!assetServices) {
+            throw new Error('FilesClientService: assetServices is not configured (CONFIGURATION_SERVICE)');
+        }
+        const tenant = await this.tenant(tenantId);
+        if (!tenant) {
+            throw new Error('FilesClientService: no tenant (pass tenantId or provide TENANT_ID_PROVIDER)');
+        }
+        const base = assetServices.endsWith('/') ? assetServices : `${assetServices}/`;
+        return `${base}${encodeURIComponent(tenant)}/v1/files/${segments.map(encodeURIComponent).join('/')}`;
+    }
+    async tenant(tenantId) {
+        return tenantId ?? (this.tenantIdProvider ? await this.tenantIdProvider() : null);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: FilesClientService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: FilesClientService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: FilesClientService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+/** Thrown for a path or rtId the bytes API cannot address (empty root, `.` or `..` segments, empty rtId). */
+class FilesPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FilesPathError';
+    }
+}
+/**
+ * Reads the file API problem details from an error of {@link FilesClientService} (`HttpErrorResponse`
+ * with a JSON object or JSON string body). Returns `null` for anything that is no HTTP error.
+ * A bare 403 / 413 without a code (e.g. nginx's body limit) maps to `FORBIDDEN` / `LIMIT_EXCEEDED`.
+ */
+function parseFilesProblem(error) {
+    if (!(error instanceof HttpErrorResponse)) {
+        return null;
+    }
+    let body = error.error;
+    if (typeof body === 'string') {
+        try {
+            body = JSON.parse(body);
+        }
+        catch {
+            body = null;
+        }
+    }
+    const problem = body && typeof body === 'object' ? body : {};
+    let code = typeof problem.code === 'string' && problem.code ? problem.code : null;
+    if (!code && typeof problem.title === 'string' && /^[A-Z][A-Z_]+$/.test(problem.title)) {
+        code = problem.title;
+    }
+    if (!code && error.status === 403) {
+        code = 'FORBIDDEN';
+    }
+    if (!code && error.status === 413) {
+        code = 'LIMIT_EXCEEDED';
+    }
+    return { status: error.status, code, detail: typeof problem.detail === 'string' ? problem.detail : null };
+}
+/**
+ * Reads the file system code (`extensions.code`, e.g. NAME_CONFLICT, PROTECTED_ROOT, RESERVED_NAME,
+ * MOVE_INTO_ITSELF, FORBIDDEN) from a GraphQL error of a `System.Files` mutation (Apollo 4
+ * `CombinedGraphQLErrors.errors`, or a raw `graphQLErrors` / `errors` array). `null` when none is found.
+ */
+function filesGraphQlErrorCode(error) {
+    if (!error || typeof error !== 'object') {
+        return null;
+    }
+    const candidate = error;
+    const list = Array.isArray(candidate.errors) ? candidate.errors : Array.isArray(candidate.graphQLErrors) ? candidate.graphQLErrors : [];
+    for (const entry of list) {
+        const code = entry?.extensions?.code;
+        if (typeof code === 'string' && code) {
+            return code;
+        }
+    }
+    return null;
+}
+function normalizeCapabilities(body) {
+    const b = body ?? {};
+    return {
+        ...b,
+        // A tenant-aware server may answer available:false (+ reason) with 200; keep it.
+        available: b.available !== false,
+        apiVersion: typeof b.apiVersion === 'number' ? b.apiVersion : 1,
+        zipDownload: b.zipDownload === true,
+        recursiveDelete: b.recursiveDelete === true,
+        folderStats: b.folderStats === true,
+        linkedCounts: b.linkedCounts === true,
+        reservedRootNames: (Array.isArray(b.reservedRootNames) && b.reservedRootNames.length > 0 ? b.reservedRootNames : FILES_RESERVED_ROOT_NAMES)
+            .map((n) => n.toLowerCase()),
+    };
+}
+function normalizeStats(body) {
+    const b = body ?? {};
+    return {
+        folders: b.folders ?? 0,
+        files: b.files ?? 0,
+        bytes: b.bytes ?? 0,
+        linkedFiles: b.linkedFiles ?? 0,
+        hiddenEntries: b.hiddenEntries ?? 0,
+        complete: b.complete !== false,
+        linkedSamples: (b.linkedSamples ?? []).map((s) => ({ ...s, entities: s.entities ?? [] })),
+    };
+}
+/**
+ * Blob requests deliver their error body as a `Blob`; this rethrows the error with the parsed problem
+ * details (or the text) as body, so {@link parseFilesProblem} works for downloads as well.
+ */
+async function withProblemBody(request) {
+    try {
+        return await request;
+    }
+    catch (error) {
+        if (error instanceof HttpErrorResponse && error.error instanceof Blob) {
+            const body = await readBlobBody(error.error);
+            throw new HttpErrorResponse({
+                error: body,
+                headers: error.headers,
+                status: error.status,
+                statusText: error.statusText,
+                url: error.url ?? undefined,
+            });
+        }
+        throw error;
+    }
+}
+async function readBlobBody(blob) {
+    let text;
+    try {
+        text = await blob.text();
+    }
+    catch {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** Emits once the signal aborts (also when it is already aborted). */
+function abortOf(signal) {
+    return signal.aborted ? from([true]) : fromEvent(signal, 'abort');
+}
+function checkRtId(rtId) {
+    if (!rtId || isDotSegment(rtId) || rtId.includes('/')) {
+        throw new FilesPathError(`Invalid rtId: ${rtId}`);
+    }
+    return rtId;
+}
+function isDotSegment(segment) {
+    return segment === '.' || segment === '..';
+}
+function callerHandled(statuses = CALLER_HANDLED) {
+    return new HttpContext().set(MM_CALLER_HANDLED_STATUSES, statuses);
+}
+function joinSegments(...parts) {
+    return parts.flatMap((p) => p.split('/')).filter((p) => p.length > 0).join('/');
+}
+
 /**
  * Service for communication controller operations.
  * Handles adapter deployment, pipeline execution, and debugging.
@@ -7849,5 +8469,5 @@ function provideOctoServices(octoServiceOptions) {
  * Generated bundle index. Do not edit.
  */
 
-export { AggregationInputTypesDto, AggregationTypeDto, AggregationTypesDto, AiService, ArchiveStorageHealthDto, AssetRepoGraphQlDataSource, AssetRepoService, AssociationModOptionsDto, AttributeOwnershipDto, AttributeSelectorService, AttributeValueTypeDto, BasicEnergyCarrierTypeDto, BasicEnergyDataQualityDto, BasicEnergyFacilityTypeDto, BasicEnergyProductionTypeDto, BasicEnergyStateDto, BasicLegalEntityTypeDto, BasicSalutationDto, BasicTypeOfTelephoneBasicDto, BasicTypeOfTelephoneEnhancedDto, BasicUnitOfMeasureDto, BlueprintConflictResolutionDto, BlueprintUpdateModeDto, BotSecretsService, BotService, BucketAlignmentDto, BucketAlignmentInputDto, CONFIGURATION_SERVICE, CREDENTIAL_ATTRIBUTE_NAME_SUFFIXES, CkExtensionUpdateOperationsDto, CkModelCatalogService, CkModelService, CkRollupFunctionDto, CkTypeAttributeService, CkTypeMetaData, CkTypeSelectorService, CommunicationService, DEFAULT_SECRET_STATUS_LABELS, DeepGraphDirectionDto, DeleteStrategiesDto, DeploymentState, EnergyCommunityBillingCycleDto, EnergyCommunityBillingDocumentStateDto, EnergyCommunityBillingTypeDto, EnergyCommunityTaxProcedureCreditNoteDto, EnvironmentCarbonScopeDto, EnvironmentComplianceCategoryDto, EnvironmentComplianceStatusDto, EnvironmentEnergySourceDto, EnvironmentGoalStateDto, FieldFilterOperatorsDto, FormulaResultTypeDto, GetCkModelByIdDocumentDto, GetCkModelByIdDtoGQL, GetCkRecordAttributesDocumentDto, GetCkRecordAttributesDtoGQL, GetCkTypeAttributesDocumentDto, GetCkTypeAttributesDtoGQL, GetCkTypeAvailableQueryColumnsDocumentDto, GetCkTypeAvailableQueryColumnsDtoGQL, GetCkTypesDocumentDto, GetCkTypesDtoGQL, GetDerivedCkTypesDocumentDto, GetDerivedCkTypesDtoGQL, GetEntitiesByCkTypeDocumentDto, GetEntitiesByCkTypeDtoGQL, GraphDirectionDto, GraphQL, GraphQLCloneIgnoredProperties, GraphQLCommonIgnoredProperties, GraphQlDataSource, HealthService, HealthStatus, IDENTITY_PROVIDER_TYPE_LABELS, IdentityProviderType, IdentityService, ImportStrategyDto, IndustryBasicAlarmPriorityDto, IndustryBasicAlarmSourceTypeDto, IndustryBasicAlarmStateDto, IndustryBasicAlarmTypeDto, IndustryBasicIecDataTypeDto, IndustryBasicMachineCapabilitiesDto, IndustryBasicMachineStateDto, IndustryEnergyDemandResponseMarketDto, IndustryEnergyDemandResponseStatusDto, IndustryEnergyTariffTypeDto, IndustryMaintenanceAggregationTypeDto, IndustryMaintenanceCostCategoryDto, IndustryMaintenanceEnergyBalanceGroupDto, IndustryMaintenanceEnergyBalanceProductDto, IndustryMaintenanceEnergyBalanceUnitDto, IndustryMaintenanceOrderPriorityDto, IndustryMaintenanceOrderStateDto, IndustryMaintenanceOrderTypeDto, IndustryMaintenanceServiceTypeDto, IndustryManufacturingFeedbackSyncStateDto, IndustryManufacturingProductionOrderItemStateDto, IndustryManufacturingProductionOrderStateDto, JobManagementService, LevelMetaData, LoggerSeverity, ModelStateDto, MultiplicitiesDto, NavigationFilterModeDto, OCTO_SILENT_ERRORS, OctoErrorLink, OctoGraphQLServiceBase, OctoSdkDemoCustomerStatusDto, OctoSdkDemoNetworkOperatorDto, OctoSdkDemoOperatingStatusDto, OctoServiceOptions, OctoServicesModule, PagedGraphResultDto, ProgressValue, ProgressWindowService, QueryModeDto, ReportingService, RtAssociationMetaData, RuntimeEntityDialogDataSource, RuntimeEntitySelectDataSource, SECRET_DUMP_RESTORE_ERROR_DUMP_DELETED, SECRET_DUMP_RESTORE_ERROR_DUMP_KEY_MISSING, SECRET_LEGACY_V1_KEY_ID, SECRET_STATUS_WARNING_DUMP_KEY_MISSING, SECRET_STATUS_WARNING_NO_KEY_RING, SECRET_STATUS_WARNING_NO_LEGACY_V1_KEY, SECRET_VALUE_TYPE, SearchFilterTypesDto, SecretStorageFormDto, SecretUsageMatchDto, SeriesComparisonPolicyDto, SeriesResolutionSignalDto, SortOrdersDto, SystemAggregationTypesDto, SystemAiApprovalModeDto, SystemAiApprovalReasonDto, SystemAiApprovalStatusDto, SystemAiAuthModeDto, SystemAiConflictModeDto, SystemAiCredentialKindDto, SystemAiJobKindDto, SystemAiJobStatusDto, SystemAiKnowledgeKindDto, SystemAiLeaseStatusDto, SystemAiModelTierDto, SystemAiRiskLevelDto, SystemAiSessionEventKindDto, SystemAiSessionStatusDto, SystemAiSubscriptionScopeDto, SystemAiTicketScopeDto, SystemAiTicketStatusDto, SystemAiWorkspaceModeDto, SystemCommunicationAdapterSharingModeDto, SystemCommunicationCommunicationStateDto, SystemCommunicationConfigurationStateDto, SystemCommunicationDeploymentStateDto, SystemCommunicationEnvironmentDto, SystemCommunicationHelmChannelDto, SystemCommunicationHelmRepositoryPurposeDto, SystemCommunicationLifecycleModeDto, SystemCommunicationLifecycleStateDto, SystemCommunicationPipelineExecutionClassDto, SystemCommunicationPipelineExecutionStatusDto, SystemCommunicationPipelineTriggerTypeDto, SystemCommunicationPoolScaleUpPolicyDto, SystemCommunicationSignalRegistrationActionDto, SystemCommunicationSignalRegistrationStateDto, SystemEnvironmentModesDto, SystemFieldFilterOperatorDto, SystemIdentityDataPolicyEnforcementModeDto, SystemIdentityDataPolicyScopeDto, SystemIdentityIdentifierKindDto, SystemIdentityIdentifierSourceDto, SystemIdentityTokenExpirationDto, SystemIdentityTokenTypeDto, SystemIdentityTokenUsageDto, SystemIdentityTrustLevelDto, SystemMaintenanceLevelsDto, SystemNavigationFilterModesDto, SystemNotificationEventLevelsDto, SystemNotificationEventSourcesDto, SystemNotificationEventStatesDto, SystemNotificationNotificationTypesDto, SystemNotificationRenderingTypesDto, SystemQueryTypesDto, SystemSortOrdersDto, SystemStreamDataBucketAlignmentDto, SystemStreamDataCkArchiveStatusDto, SystemStreamDataCkComputedColumnResultTypeDto, SystemStreamDataCkComputedColumnStateDto, SystemStreamDataCkConflictKeyOrderDto, SystemStreamDataCkRecomputeChangeKindDto, SystemStreamDataCkRecomputeChangeSourceDto, SystemStreamDataCkRecomputeJobStateDto, SystemStreamDataCkRecomputeTriggerDto, SystemStreamDataCkRollupFunctionDto, TENANT_ID_PROVIDER, TusUploadService, UpdateTypeDto, buildTusEndpoint, formatSecretStatus, isCredentialLikeAttributeName, isSecretAttributeCandidate, isSecretPresent, isSecretQueryColumn, isSecretStateObject, isSecretValueType, isTextualValueType, octoDataIdFromObject, result as possibleTypes, provideOctoServices, secretInputValue, secretStateFromAttribute, secretStatusOf, toAttributeNameFilter, toCamelCaseAttributeName, toSecretState, toUniqueCamelCaseNames };
+export { AggregationInputTypesDto, AggregationTypeDto, AggregationTypesDto, AiService, ArchiveStorageHealthDto, AssetRepoGraphQlDataSource, AssetRepoService, AssociationModOptionsDto, AttributeOwnershipDto, AttributeSelectorService, AttributeValueTypeDto, BasicEnergyCarrierTypeDto, BasicEnergyDataQualityDto, BasicEnergyFacilityTypeDto, BasicEnergyProductionTypeDto, BasicEnergyStateDto, BasicLegalEntityTypeDto, BasicSalutationDto, BasicTypeOfTelephoneBasicDto, BasicTypeOfTelephoneEnhancedDto, BasicUnitOfMeasureDto, BinaryDownloadUnavailableError, BlueprintConflictResolutionDto, BlueprintUpdateModeDto, BotSecretsService, BotService, BucketAlignmentDto, BucketAlignmentInputDto, CONFIGURATION_SERVICE, CREDENTIAL_ATTRIBUTE_NAME_SUFFIXES, CkExtensionUpdateOperationsDto, CkModelCatalogService, CkModelService, CkRollupFunctionDto, CkTypeAttributeService, CkTypeMetaData, CkTypeSelectorService, CommunicationService, DEFAULT_SECRET_STATUS_LABELS, DeepGraphDirectionDto, DeleteStrategiesDto, DeploymentState, EnergyCommunityBillingCycleDto, EnergyCommunityBillingDocumentStateDto, EnergyCommunityBillingTypeDto, EnergyCommunityTaxProcedureCreditNoteDto, EnvironmentCarbonScopeDto, EnvironmentComplianceCategoryDto, EnvironmentComplianceStatusDto, EnvironmentEnergySourceDto, EnvironmentGoalStateDto, FILES_LINKED_COUNTS_MAX, FILES_RESERVED_ROOT_NAMES, FILES_UNAVAILABLE_TTL_MS, FieldFilterOperatorsDto, FileDownloadService, FilesClientService, FilesPathError, FormulaResultTypeDto, GetCkModelByIdDocumentDto, GetCkModelByIdDtoGQL, GetCkRecordAttributesDocumentDto, GetCkRecordAttributesDtoGQL, GetCkTypeAttributesDocumentDto, GetCkTypeAttributesDtoGQL, GetCkTypeAvailableQueryColumnsDocumentDto, GetCkTypeAvailableQueryColumnsDtoGQL, GetCkTypesDocumentDto, GetCkTypesDtoGQL, GetDerivedCkTypesDocumentDto, GetDerivedCkTypesDtoGQL, GetEntitiesByCkTypeDocumentDto, GetEntitiesByCkTypeDtoGQL, GraphDirectionDto, GraphQL, GraphQLCloneIgnoredProperties, GraphQLCommonIgnoredProperties, GraphQlDataSource, HealthService, HealthStatus, IDENTITY_PROVIDER_TYPE_LABELS, IdentityProviderType, IdentityService, ImportStrategyDto, IndustryBasicAlarmPriorityDto, IndustryBasicAlarmSourceTypeDto, IndustryBasicAlarmStateDto, IndustryBasicAlarmTypeDto, IndustryBasicIecDataTypeDto, IndustryBasicMachineCapabilitiesDto, IndustryBasicMachineStateDto, IndustryEnergyDemandResponseMarketDto, IndustryEnergyDemandResponseStatusDto, IndustryEnergyTariffTypeDto, IndustryMaintenanceAggregationTypeDto, IndustryMaintenanceCostCategoryDto, IndustryMaintenanceEnergyBalanceGroupDto, IndustryMaintenanceEnergyBalanceProductDto, IndustryMaintenanceEnergyBalanceUnitDto, IndustryMaintenanceOrderPriorityDto, IndustryMaintenanceOrderStateDto, IndustryMaintenanceOrderTypeDto, IndustryMaintenanceServiceTypeDto, IndustryManufacturingFeedbackSyncStateDto, IndustryManufacturingProductionOrderItemStateDto, IndustryManufacturingProductionOrderStateDto, JobManagementService, LevelMetaData, LoggerSeverity, ModelStateDto, MultiplicitiesDto, NavigationFilterModeDto, OCTO_SILENT_ERRORS, OctoErrorLink, OctoGraphQLServiceBase, OctoSdkDemoCustomerStatusDto, OctoSdkDemoNetworkOperatorDto, OctoSdkDemoOperatingStatusDto, OctoServiceOptions, OctoServicesModule, PagedGraphResultDto, ProgressValue, ProgressWindowService, QueryModeDto, ReportingService, RtAssociationMetaData, RuntimeEntityDialogDataSource, RuntimeEntitySelectDataSource, SECRET_DUMP_RESTORE_ERROR_DUMP_DELETED, SECRET_DUMP_RESTORE_ERROR_DUMP_KEY_MISSING, SECRET_LEGACY_V1_KEY_ID, SECRET_STATUS_WARNING_DUMP_KEY_MISSING, SECRET_STATUS_WARNING_NO_KEY_RING, SECRET_STATUS_WARNING_NO_LEGACY_V1_KEY, SECRET_VALUE_TYPE, SearchFilterTypesDto, SecretStorageFormDto, SecretUsageMatchDto, SeriesComparisonPolicyDto, SeriesResolutionSignalDto, SortOrdersDto, SystemAggregationTypesDto, SystemAiApprovalModeDto, SystemAiApprovalReasonDto, SystemAiApprovalStatusDto, SystemAiAuthModeDto, SystemAiConflictModeDto, SystemAiCredentialKindDto, SystemAiJobKindDto, SystemAiJobStatusDto, SystemAiKnowledgeKindDto, SystemAiLeaseStatusDto, SystemAiModelTierDto, SystemAiRiskLevelDto, SystemAiSessionEventKindDto, SystemAiSessionStatusDto, SystemAiSubscriptionScopeDto, SystemAiTicketScopeDto, SystemAiTicketStatusDto, SystemAiWorkspaceModeDto, SystemCommunicationAdapterSharingModeDto, SystemCommunicationCommunicationStateDto, SystemCommunicationConfigurationStateDto, SystemCommunicationDeploymentStateDto, SystemCommunicationEnvironmentDto, SystemCommunicationHelmChannelDto, SystemCommunicationHelmRepositoryPurposeDto, SystemCommunicationLifecycleModeDto, SystemCommunicationLifecycleStateDto, SystemCommunicationPipelineExecutionClassDto, SystemCommunicationPipelineExecutionStatusDto, SystemCommunicationPipelineTriggerTypeDto, SystemCommunicationPoolScaleUpPolicyDto, SystemCommunicationSignalRegistrationActionDto, SystemCommunicationSignalRegistrationStateDto, SystemEnvironmentModesDto, SystemFieldFilterOperatorDto, SystemIdentityDataPolicyEnforcementModeDto, SystemIdentityDataPolicyScopeDto, SystemIdentityIdentifierKindDto, SystemIdentityIdentifierSourceDto, SystemIdentityTokenExpirationDto, SystemIdentityTokenTypeDto, SystemIdentityTokenUsageDto, SystemIdentityTrustLevelDto, SystemMaintenanceLevelsDto, SystemNavigationFilterModesDto, SystemNotificationEventLevelsDto, SystemNotificationEventSourcesDto, SystemNotificationEventStatesDto, SystemNotificationNotificationTypesDto, SystemNotificationRenderingTypesDto, SystemQueryTypesDto, SystemSortOrdersDto, SystemStreamDataBucketAlignmentDto, SystemStreamDataCkArchiveStatusDto, SystemStreamDataCkComputedColumnResultTypeDto, SystemStreamDataCkComputedColumnStateDto, SystemStreamDataCkConflictKeyOrderDto, SystemStreamDataCkRecomputeChangeKindDto, SystemStreamDataCkRecomputeChangeSourceDto, SystemStreamDataCkRecomputeJobStateDto, SystemStreamDataCkRecomputeTriggerDto, SystemStreamDataCkRollupFunctionDto, TENANT_ID_PROVIDER, TusUploadService, UpdateTypeDto, buildTusEndpoint, filesGraphQlErrorCode, formatSecretStatus, isCredentialLikeAttributeName, isSecretAttributeCandidate, isSecretPresent, isSecretQueryColumn, isSecretStateObject, isSecretValueType, isTextualValueType, octoDataIdFromObject, parseContentDispositionFileName, parseFilesProblem, result as possibleTypes, provideOctoServices, secretInputValue, secretStateFromAttribute, secretStatusOf, toAttributeNameFilter, toCamelCaseAttributeName, toSecretState, toUniqueCamelCaseNames };
 //# sourceMappingURL=meshmakers-octo-services.mjs.map