@collage-dam/mcp-server 0.1.0

package/dist/client.js

@@ -0,0 +1,1162 @@
+import { z } from 'zod';
+import { createToolError, mapHttpStatusToErrorCode, } from './conventions/errors.js';
+import { RateLimitedError, TokenBucketRateLimiter, withRetry, } from './conventions/rate-limiter.js';
+import { generateRequestId, logger as defaultLogger } from './conventions/logger.js';
+import { AssetCustomFieldSchema, CategoryListSchema, CollectionListSchema, CustomFieldListSchema, DigitalAssetSchema, GenerateEmbedCodeResponseSchema, GenerateShareLinkResponseSchema, PaginatedAssetsEnvelopeSchema, ShareLinkListEnvelopeSchema, SimpleMessageEnvelopeSchema, unwrapEnvelope, } from './types.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Schema for the `check-workspace-access` response payload.
+ * The endpoint may wrap fields under a top-level `data` envelope, so we
+ * accept either shape and normalise downstream.
+ */
+const WorkspaceAccessSchema = z.object({
+    has_access: z.boolean().optional(),
+    status: z.boolean().optional(),
+    message: z.string().optional(),
+});
+const WorkspaceAccessEnvelopeSchema = z.object({
+    data: WorkspaceAccessSchema.optional(),
+    status: z.boolean().optional(),
+    message: z.string().optional(),
+    has_access: z.boolean().optional(),
+});
+/**
+ * HTTP client for the Collage DAM REST API.
+ *
+ * Responsibilities:
+ *  - Bearer JWT auth (token from `COLLAGE_API_KEY`)
+ *  - Workspace scoping via `?url_workspace_id=` on every request
+ *  - Token-bucket rate limiting
+ *  - Retry with exponential backoff on 429/5xx (honours `Retry-After`)
+ *  - HTTP status → canonical `McpToolError` mapping
+ *  - Per-request `request_id` propagation for tracing
+ */
+export class CollageClient {
+    baseUrl;
+    apiKey;
+    workspaceId;
+    limiter;
+    log;
+    constructor(opts) {
+        this.baseUrl = opts.config.collageApiUrl.endsWith('/')
+            ? opts.config.collageApiUrl
+            : `${opts.config.collageApiUrl}/`;
+        this.apiKey = opts.config.collageApiKey;
+        this.workspaceId = opts.config.collageWorkspaceId;
+        this.limiter = opts.rateLimiter ?? new TokenBucketRateLimiter({ maxRps: opts.config.maxRps });
+        this.log = opts.logger ?? defaultLogger;
+    }
+    /** Workspace ID associated with this client (read-only). */
+    get scopedWorkspaceId() {
+        return this.workspaceId;
+    }
+    async get(path, options) {
+        return this.request('GET', path, options);
+    }
+    async post(path, options) {
+        return this.request('POST', path, options);
+    }
+    async put(path, options) {
+        return this.request('PUT', path, options);
+    }
+    async patch(path, options) {
+        return this.request('PATCH', path, options);
+    }
+    async delete(path, options) {
+        return this.request('DELETE', path, options);
+    }
+    /**
+     * Perform a startup sanity check that the configured token can reach the
+     * configured workspace. Returns a normalised access result.
+     *
+     * Used by `src/index.ts` on boot to fail fast on misconfiguration.
+     */
+    async checkWorkspaceAccess() {
+        const result = await this.get('check-workspace-access');
+        if (!result.ok) {
+            return result;
+        }
+        const parsed = WorkspaceAccessEnvelopeSchema.safeParse(result.data);
+        if (!parsed.success) {
+            return {
+                ok: false,
+                request_id: result.request_id,
+                error: createToolError('UPSTREAM', 'check-workspace-access returned an unexpected shape', {
+                    cause: { request_id: result.request_id },
+                }),
+            };
+        }
+        const inner = parsed.data.data ?? {};
+        const hasAccess = inner.has_access ?? parsed.data.has_access ?? inner.status ?? parsed.data.status ?? false;
+        const message = inner.message ?? parsed.data.message;
+        return {
+            ok: true,
+            request_id: result.request_id,
+            data: { has_access: hasAccess, ...(message !== undefined ? { message } : {}) },
+        };
+    }
+    /**
+     * GET /digital-assets/category/all-category-list
+     *
+     * Returns ROOT-LEVEL folders only — upstream is flat-by-design. Verified
+     * against `Admin-Frontend/pages/_workspace_id/dam/folders/index.vue` (the
+     * Folders index page calls this endpoint with the same params and only
+     * shows roots; nested folders load via `sub-category-list` on click).
+     *
+     * Use `listAllCategoriesRecursive()` when you need the full tree.
+     *
+     * Requires `workspace_id` in the query in addition to the global
+     * `?url_workspace_id=`. Without both, the upstream returns 402
+     * "Workspace is not available." (Ross Durbin, 2026-05-01.)
+     */
+    async listCategories() {
+        return this.parsedGet('digital-assets/category/all-category-list', CategoryListSchema, { query: { workspace_id: this.workspaceId } });
+    }
+    /**
+     * Walks the workspace folder tree by combining `listCategories()` (roots)
+     * with `listSubCategories()` for each parent. Returns a flat list with
+     * `parent_id` populated on every row — null for roots — so callers can
+     * reconstruct the tree without recursing themselves.
+     *
+     * Behavior:
+     * - Breadth-first traversal, deduped by category id.
+     * - Bounded by `maxNodes` (default 5000) and `maxDepth` (default 16) to
+     *   keep audit/enumeration runs predictable on huge workspaces.
+     * - Any non-ok subcategory fetch aborts the walk and propagates the error.
+     */
+    async listAllCategoriesRecursive(opts) {
+        const maxNodes = opts?.maxNodes ?? 5000;
+        const maxDepth = opts?.maxDepth ?? 16;
+        const roots = await this.listCategories();
+        if (!roots.ok)
+            return roots;
+        const seen = new Set();
+        const out = [];
+        let frontier = [];
+        for (const r of roots.data) {
+            const key = String(r.id);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const root = { ...r, parent_id: r.parent_id ?? null };
+            out.push(root);
+            if (out.length >= maxNodes)
+                break;
+            frontier.push({ cat: root, depth: 0 });
+        }
+        while (frontier.length > 0 && out.length < maxNodes) {
+            const next = [];
+            for (const { cat, depth } of frontier) {
+                if (depth + 1 > maxDepth)
+                    continue;
+                const subs = await this.listSubCategories(cat.id);
+                if (!subs.ok) {
+                    return { ok: false, error: subs.error, request_id: subs.request_id };
+                }
+                for (const child of subs.data) {
+                    const key = String(child.id);
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    const node = { ...child, parent_id: child.parent_id ?? cat.id };
+                    out.push(node);
+                    if (out.length >= maxNodes)
+                        break;
+                    next.push({ cat: node, depth: depth + 1 });
+                }
+                if (out.length >= maxNodes)
+                    break;
+            }
+            frontier = next;
+        }
+        return { ok: true, data: out, request_id: generateRequestId() };
+    }
+    /**
+     * GET /digital-assets/category/sub-category-list
+     * Returns the immediate children of a folder. Same row shape as
+     * `all-category-list`. Requires `workspace_id` + `category_id` in the
+     * query in addition to the global `?url_workspace_id=`.
+     */
+    async listSubCategories(categoryId) {
+        return this.parsedGet('digital-assets/category/sub-category-list', CategoryListSchema, {
+            query: {
+                workspace_id: this.workspaceId,
+                category_id: String(categoryId),
+            },
+        });
+    }
+    /**
+     * GET /digital-assets/instance/get
+     * Returns the portal/instance configuration for the workspace. Shape is
+     * upstream-defined and not yet narrowed; callers should treat the result
+     * as opaque until a tool needs specific fields.
+     */
+    async getInstance() {
+        return this.parsedGet('digital-assets/instance/get', z.unknown(), { query: { workspace_id: this.workspaceId } });
+    }
+    /**
+     * GET /digital-assets/dashboard/common-data
+     * Returns workspace dashboard stats (asset counts, storage, etc.). Shape
+     * is upstream-defined; narrow when wiring an insights tool.
+     */
+    async getDashboardCommonData() {
+        return this.parsedGet('digital-assets/dashboard/common-data', z.unknown(), { query: { workspace_id: this.workspaceId } });
+    }
+    /**
+     * GET /digital-assets/get-recent-uploaded
+     * Paginated list of recently-uploaded assets. Shape mirrors the standard
+     * paginated-asset response but is left opaque here; narrow when wiring
+     * the `collage://assets/recent` resource.
+     */
+    async listRecentUploaded(params) {
+        return this.parsedGet('digital-assets/get-recent-uploaded', z.unknown(), {
+            query: {
+                workspace_id: this.workspaceId,
+                page: params.page,
+                total_record: params.totalRecord,
+            },
+        });
+    }
+    /**
+     * POST /digital-assets/category/add  (parent_id absent)
+     * POST /digital-assets/category/add-sub-category  (parent_id present)
+     *
+     * Source: `Admin-Frontend/components/dam/Dialogs/miniUploadBackdrop.vue:358,366`.
+     * Body shape:
+     *   - top-level: { workspace_id, folder_name }
+     *   - sub-folder: { workspace_id, folder_name, category_id }
+     * The two endpoints differ only by path; the body for sub-folders adds the
+     * parent's id under the (confusingly named) `category_id` key.
+     *
+     * Returns the new folder's id when the upstream surfaces it. The Collage
+     * envelope nests the projection under `data.id`; we tolerate either
+     * `data.id` or a top-level `id` field.
+     */
+    async createCategory(input) {
+        const path = input.parent_id !== undefined && input.parent_id !== null
+            ? 'digital-assets/category/add-sub-category'
+            : 'digital-assets/category/add';
+        const body = {
+            workspace_id: this.workspaceId,
+            folder_name: input.folder_name,
+        };
+        if (input.parent_id !== undefined && input.parent_id !== null) {
+            body['category_id'] = input.parent_id;
+        }
+        const raw = await this.post(path, { body });
+        if (!raw.ok)
+            return raw;
+        const id = extractCreatedCategoryId(raw.data);
+        if (id === null) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', 'category/add response missing folder id', { cause: { request_id: raw.request_id } }),
+            };
+        }
+        return { ok: true, request_id: raw.request_id, data: { id } };
+    }
+    /**
+     * POST /digital-assets/category/rename/{id}
+     * Source: `Admin-Frontend/pages/_workspace_id/dam/folders/index.vue:1281`.
+     * Body: { workspace_id, folder_name, description? }
+     */
+    async renameCategory(categoryId, input) {
+        const body = {
+            workspace_id: this.workspaceId,
+            folder_name: input.folder_name,
+        };
+        if (input.description !== undefined) {
+            body['description'] = input.description ?? '';
+        }
+        const raw = await this.post(`digital-assets/category/rename/${encodeURIComponent(String(categoryId))}`, { body });
+        if (!raw.ok)
+            return raw;
+        const message = extractMessage(raw.data);
+        return {
+            ok: true,
+            request_id: raw.request_id,
+            data: message !== undefined ? { message } : {},
+        };
+    }
+    /**
+     * POST /digital-assets/multiple-file-folder-move
+     * Source: `Admin-Frontend/components/dam/Dialogs/FolderDialogs/FolderDialog.vue:1471`.
+     * Body: { workspace_id, assets_ids: number[], category_ids: number[], move_id: destFolderId }
+     *
+     * `move_id` is the destination category id. Pass null to move into the
+     * uncategorised root (the frontend uses null when destination is "no
+     * folder" — verify against your workspace before relying on that).
+     */
+    async moveAssetsAndFolders(input) {
+        const raw = await this.post('digital-assets/multiple-file-folder-move', {
+            body: {
+                workspace_id: this.workspaceId,
+                assets_ids: input.asset_ids,
+                category_ids: input.folder_ids,
+                move_id: input.destination_id,
+            },
+        });
+        if (!raw.ok)
+            return raw;
+        const message = extractMessage(raw.data);
+        return {
+            ok: true,
+            request_id: raw.request_id,
+            data: message !== undefined ? { message } : {},
+        };
+    }
+    /**
+     * GET /digital-assets/collection/get-all
+     * Returns the user's saved DAM collections for the workspace.
+     */
+    async listCollections() {
+        return this.parsedGet('digital-assets/collection/get-all', CollectionListSchema);
+    }
+    /**
+     * GET /digital-assets/collection/get-all (filtered to a single id).
+     *
+     * The Collage REST API exposes only a list endpoint for collections;
+     * there is no per-id route. We fetch the full list and filter
+     * client-side so the MCP `get_collection` tool has the same single-row
+     * read affordance as the rest of the read-side API surface. For
+     * workspaces with thousands of collections this trade-off is fine:
+     * the list is small (< few hundred typical) and the upstream caches it.
+     */
+    async getCollection(collectionId) {
+        const list = await this.listCollections();
+        if (!list.ok)
+            return list;
+        const target = String(collectionId);
+        const match = list.data.find((c) => String(c.id) === target);
+        if (match === undefined) {
+            return {
+                ok: false,
+                request_id: list.request_id,
+                error: createToolError('NOT_FOUND', `Collection ${collectionId} not found in workspace.`, { cause: { request_id: list.request_id } }),
+            };
+        }
+        return { ok: true, data: match, request_id: list.request_id };
+    }
+    /**
+     * GET /digital-assets/custom-field/list
+     *
+     * Returns the workspace-scoped custom-field definitions. Source:
+     * `Admin-Frontend/pages/_workspace_id/workspace-settings/custom-fields/index.vue:144`.
+     * Each row is shaped `{ id, field_label, field_type, status, ... }`.
+     * The endpoint requires `workspace_id` in the query string in addition
+     * to the global `?url_workspace_id=` (Collage uses both names — the
+     * frontend always sends both).
+     */
+    async listCustomFields() {
+        const raw = await this.get('digital-assets/custom-field/list', {
+            query: { workspace_id: this.workspaceId },
+        });
+        if (!raw.ok)
+            return raw;
+        try {
+            const parsed = unwrapEnvelope(raw.data, CustomFieldListSchema);
+            return { ok: true, data: parsed, request_id: raw.request_id };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', `Schema mismatch on custom-field/list: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+            };
+        }
+    }
+    /**
+     * POST /digital-assets/view-detail
+     * Returns full metadata for a single asset.
+     *
+     * Field-name quirk: the body param is `digital_assets_id`, NOT `asset_id`.
+     * The response is a richer projection than the raw `digital_assets` row —
+     * it joins in tag rows, breadcrumb, formatted file metadata, and signed
+     * S3 thumbnail/compress URLs (24h expiry).
+     *
+     * Read paths (`getAssetCurrentName`, `getAssetMetadata`, `getAssetTags`)
+     * are intentionally implemented as projections of this single response —
+     * see the adapters in `src/tools/client-adapters.ts`. There is no
+     * dedicated REST endpoint per field; the Admin-Frontend reads everything
+     * via this same `view-detail` call.
+     */
+    async getAssetDetails(assetId) {
+        const raw = await this.post('digital-assets/view-detail', {
+            body: { digital_assets_id: assetId },
+        });
+        if (!raw.ok)
+            return raw;
+        try {
+            const parsed = unwrapEnvelope(raw.data, DigitalAssetSchema);
+            return { ok: true, data: parsed, request_id: raw.request_id };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', `Schema mismatch on view-detail: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+            };
+        }
+    }
+    /**
+     * GET /digital-assets/embed-code-list
+     * Returns the embed-code share-link configurations.
+     *
+     * Schema is intentionally `unknown` until we observe a live response —
+     * keep the raw passthrough so the smoke tool can render whatever the
+     * upstream returns without rejecting fields we have not modelled yet.
+     */
+    async listEmbedCodes() {
+        return this.get('digital-assets/embed-code-list');
+    }
+    /**
+     * POST /digital-assets/collection/create
+     * Body: { name, description? }
+     * Returns: envelope with { id, name, description, ... }
+     */
+    async createCollection(body) {
+        const raw = await this.post('digital-assets/collection/create', {
+            body,
+        });
+        if (!raw.ok)
+            return raw;
+        return parseCollectionMutationResponse(raw);
+    }
+    /**
+     * POST /digital-assets/collection/update/{id}
+     * Body: { name?, description? }
+     * Returns: envelope with the updated collection projection. The live
+     * response on BREZ (verified 2026-04-29) omits `id` at the top level —
+     * the path id is the canonical identity, so we fall it back through.
+     */
+    async updateCollection(collectionId, body) {
+        const raw = await this.post(`digital-assets/collection/update/${encodeURIComponent(collectionId)}`, { body });
+        if (!raw.ok)
+            return raw;
+        return parseCollectionMutationResponse(raw, collectionId);
+    }
+    /**
+     * POST /digital-assets/collection/{id}/add-assets
+     * Body: { assets_id: (string|number)[] }
+     */
+    async addAssetsToCollection(collectionId, assetIds) {
+        const raw = await this.post(`digital-assets/collection/${encodeURIComponent(collectionId)}/add-assets`, { body: { assets_id: assetIds } });
+        if (!raw.ok)
+            return raw;
+        const message = extractMessage(raw.data);
+        return { ok: true, data: message !== undefined ? { message } : {}, request_id: raw.request_id };
+    }
+    /**
+     * POST /digital-assets/collection/{id}/remove-assets
+     * Body: { assets_id: (string|number)[] }
+     */
+    async removeAssetsFromCollection(collectionId, assetIds) {
+        const raw = await this.post(`digital-assets/collection/${encodeURIComponent(collectionId)}/remove-assets`, { body: { assets_id: assetIds } });
+        if (!raw.ok)
+            return raw;
+        const message = extractMessage(raw.data);
+        return { ok: true, data: message !== undefined ? { message } : {}, request_id: raw.request_id };
+    }
+    /**
+     * GET /digital-assets/category/view-files-with-category
+     *
+     * Folder-scoped paginated asset listing. Used as the REST fallback for
+     * workspace-wide enumeration (Typesense is the primary path but is not
+     * yet wired). Response shape (verified via Admin-Frontend
+     * `pages/_workspace_id/dam/folders/_id/index.vue:3357`):
+     *
+     *   { data: { assets_with_folder: { data: [...], last_page, total }, ... } }
+     *
+     * Each row in `assets_with_folder.data` is the raw `digital_assets` row
+     * (NOT the `view-detail` projection), so tag projection here only sees
+     * what `category/view-files-with-category` returns — which historically
+     * does NOT include the joined `tags` array. See `enumerateAssets` for
+     * how the audit tool tolerates that.
+     */
+    async listAssetsByCategory(categoryId, page, opts) {
+        const raw = await this.get('digital-assets/category/view-files-with-category', {
+            query: {
+                workspace_id: this.workspaceId,
+                category_id: categoryId,
+                page,
+                sort_by: opts?.sortBy ?? 'ASC',
+                sort_value: opts?.sortValue ?? 'display_file_name',
+            },
+        });
+        if (!raw.ok)
+            return raw;
+        try {
+            const parsed = unwrapEnvelope(raw.data, PaginatedAssetsEnvelopeSchema);
+            return {
+                ok: true,
+                request_id: raw.request_id,
+                data: {
+                    assets: parsed.assets_with_folder.data,
+                    lastPage: parsed.assets_with_folder.last_page ?? 1,
+                    total: parsed.assets_with_folder.total ?? parsed.assets_with_folder.data.length,
+                },
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', `Schema mismatch on view-files-with-category: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+            };
+        }
+    }
+    /**
+     * Workspace-wide flat asset enumeration via folder iteration.
+     *
+     * Walks the FULL folder tree via `listAllCategoriesRecursive()` (roots
+     * plus every sub-folder) and paginates `listAssetsByCategory()` per
+     * folder to produce a flat `{id, tags?, ...}[]`. Used by the
+     * audit-tagging-hygiene tool. Tags come from `view-detail`-shaped rows
+     * when present, otherwise the row's `tags` field (often missing on the
+     * paginator response — callers must tolerate `tags=[]`).
+     *
+     * Prior to FU3 (2026-05-04) this only walked root folders, so any asset
+     * living in a nested folder was invisible to the audit.
+     */
+    async enumerateAssets(opts) {
+        const cats = await this.listAllCategoriesRecursive();
+        if (!cats.ok)
+            return { ok: false, error: cats.error, request_id: cats.request_id };
+        const limit = opts?.maxAssets ?? 5000;
+        const seen = new Set();
+        const out = [];
+        for (const cat of cats.data) {
+            if (out.length >= limit)
+                break;
+            let page = 1;
+            let lastPage = 1;
+            do {
+                const res = await this.listAssetsByCategory(cat.id, page);
+                if (!res.ok)
+                    return { ok: false, error: res.error, request_id: res.request_id };
+                for (const row of res.data.assets) {
+                    const id = String(row.id);
+                    if (seen.has(id))
+                        continue;
+                    seen.add(id);
+                    const tagNames = Array.isArray(row.tags)
+                        ? row.tags.map((t) => t.tag_name)
+                        : [];
+                    out.push({ id, tags: tagNames });
+                    if (out.length >= limit)
+                        break;
+                }
+                lastPage = res.data.lastPage;
+                page += 1;
+            } while (page <= lastPage && out.length < limit);
+        }
+        return { ok: true, data: out, request_id: generateRequestId() };
+    }
+    /**
+     * POST /digital-assets/update-with-field
+     *
+     * Single-field update used by the Admin-Frontend rename and description
+     * edit flows. Source: `pages/_workspace_id/dam/files/_id.vue:2329` and
+     * `components/dam/SearchAssets.vue:1206`. Body shape:
+     *
+     *   { workspace_id, digital_assets_id, field_name, field_value }
+     *
+     * Note `digital_assets_id` (not `asset_id`) and `workspace_id` is in the
+     * BODY too — even though the same value is also on the URL via
+     * `?url_workspace_id=`. The frontend always sends both; we mirror that.
+     */
+    async updateAssetField(assetId, fieldName, fieldValue) {
+        const raw = await this.post('digital-assets/update-with-field', {
+            body: {
+                workspace_id: this.workspaceId,
+                digital_assets_id: assetId,
+                field_name: fieldName,
+                field_value: fieldValue,
+            },
+        });
+        if (!raw.ok)
+            return raw;
+        const parsed = SimpleMessageEnvelopeSchema.safeParse(raw.data);
+        const message = parsed.success ? parsed.data.message : undefined;
+        return {
+            ok: true,
+            request_id: raw.request_id,
+            data: message !== undefined ? { message } : {},
+        };
+    }
+    /**
+     * POST /digital-assets/update-with-field with `field_name: 'display_file_name'`.
+     *
+     * The Admin-Frontend rename UI also concatenates the file extension
+     * (`${name}.${file_type}`). We do NOT do that here — callers pass the
+     * exact `display_file_name` they want, including any extension. This
+     * keeps the client a thin pass-through and lets the rename tool decide
+     * its own extension policy.
+     */
+    async renameAsset(assetId, newName) {
+        return this.updateAssetField(assetId, 'display_file_name', newName);
+    }
+    /**
+     * GET /digital-assets/get-custom-fields
+     *
+     * Returns the per-asset custom-field projection (id, name, field_type,
+     * value, ...). Source: `pages/_workspace_id/dam/files/_id.vue:1319`.
+     * Used as the read side for `update_asset_metadata` so the dry-run plan
+     * can render a real diff. Schema is defensive — fields beyond
+     * {id, name, value} are passed through.
+     */
+    async getAssetCustomFields(assetId) {
+        // Note: this endpoint requires `workspace_id` in the query in addition to
+        // the global `?url_workspace_id=` (different param name — field-name
+        // mismatch confirmed against BREZ on 2026-04-29).
+        const raw = await this.get('digital-assets/get-custom-fields', {
+            query: { asset_id: assetId, workspace_id: this.workspaceId },
+        });
+        if (!raw.ok)
+            return raw;
+        try {
+            const parsed = unwrapEnvelope(raw.data, z.array(AssetCustomFieldSchema));
+            return { ok: true, data: parsed, request_id: raw.request_id };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', `Schema mismatch on get-custom-fields: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+            };
+        }
+    }
+    /**
+     * POST /digital-assets/update-custom-fields
+     *
+     * Bulk custom-field update. Source: `pages/_workspace_id/dam/files/_id.vue:2894`
+     * Body shape:
+     *
+     *   { workspace_id, asset_ids: [id], updated_data: [{ id, value, ... }] }
+     *
+     * Each entry in `updated_data` is the projection returned by
+     * `get-custom-fields` with its `value` overwritten — the upstream
+     * matches by the field's row id.
+     */
+    async updateAssetCustomFields(assetId, updatedFields) {
+        const raw = await this.post('digital-assets/update-custom-fields', {
+            body: {
+                workspace_id: this.workspaceId,
+                asset_ids: [assetId],
+                updated_data: updatedFields,
+            },
+        });
+        if (!raw.ok)
+            return raw;
+        const parsed = SimpleMessageEnvelopeSchema.safeParse(raw.data);
+        const message = parsed.success ? parsed.data.message : undefined;
+        return {
+            ok: true,
+            request_id: raw.request_id,
+            data: message !== undefined ? { message } : {},
+        };
+    }
+    /**
+     * POST /digital-assets/add-tags-to-multiple-file
+     *
+     * Source: `components/dam/AssetList/AddTags.vue:86`. Body:
+     *
+     *   { workspace_id, digital_assets_ids: [id, ...], tags: ['name', ...] }
+     *
+     * `tags` is an array of plain string names — the upstream creates new
+     * tag rows on demand. Idempotent on the server (duplicate adds are
+     * tolerated, surfaced via the `message` field).
+     */
+    async addTagsToAssets(assetIds, tagNames) {
+        const raw = await this.post('digital-assets/add-tags-to-multiple-file', {
+            body: {
+                workspace_id: this.workspaceId,
+                digital_assets_ids: assetIds,
+                tags: tagNames,
+            },
+        });
+        if (!raw.ok)
+            return raw;
+        const parsed = SimpleMessageEnvelopeSchema.safeParse(raw.data);
+        const message = parsed.success ? parsed.data.message : undefined;
+        return {
+            ok: true,
+            request_id: raw.request_id,
+            data: message !== undefined ? { message } : {},
+        };
+    }
+    /**
+     * POST /digital-assets/delete-tag-from-multiple-file
+     *
+     * Source: `components/dam/Dialogs/AddTags/AddMultipleTags.vue:202` —
+     * the multi-select removal path uses `tag_name` (not `tag_id`), and
+     * `digital_assets_ids` is an array of `{ id }` objects. Single-asset
+     * removal uses `tag_id` instead. We use the multi-asset / `tag_name`
+     * shape so a single client method covers full-replace.
+     *
+     *   { workspace_id, digital_assets_ids: [{ id }, ...], tag_name }
+     *
+     * One tag name per call — the upstream removes that tag from every
+     * provided asset.
+     */
+    async removeTagFromAssets(assetIds, tagName) {
+        const raw = await this.post('digital-assets/delete-tag-from-multiple-file', {
+            body: {
+                workspace_id: this.workspaceId,
+                digital_assets_ids: assetIds.map((id) => ({ id })),
+                tag_name: tagName,
+            },
+        });
+        if (!raw.ok)
+            return raw;
+        const parsed = SimpleMessageEnvelopeSchema.safeParse(raw.data);
+        const message = parsed.success ? parsed.data.message : undefined;
+        return {
+            ok: true,
+            request_id: raw.request_id,
+            data: message !== undefined ? { message } : {},
+        };
+    }
+    /**
+     * POST /digital-assets/dashboard/generate-share-assets-url
+     *
+     * Source: Admin-Frontend
+     * `components/dam/Dialogs/ShareAssetDialog/index.vue:399`. Body shape:
+     *
+     *   { workspace_id, assets: number[], category: number[], title?, description?,
+     *     password?, hide_download?: 0|1, expiration?: 'MMM D, YYYY' }
+     *
+     * Returns the generated share link projection
+     * (`{ data: { id, share_url, ... } }`).
+     */
+    async generateShareAssetsUrl(input) {
+        const body = {
+            workspace_id: this.workspaceId,
+            assets: input.assets,
+            category: input.category,
+            title: input.title ?? '',
+            description: input.description ?? null,
+        };
+        if (input.password !== undefined)
+            body['password'] = input.password;
+        if (input.hide_download !== undefined)
+            body['hide_download'] = input.hide_download;
+        if (input.expiration !== undefined)
+            body['expiration'] = input.expiration;
+        const raw = await this.post('digital-assets/dashboard/generate-share-assets-url', { body });
+        if (!raw.ok)
+            return raw;
+        try {
+            const parsed = unwrapEnvelope(raw.data, GenerateShareLinkResponseSchema);
+            return { ok: true, data: parsed, request_id: raw.request_id };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', `Schema mismatch on generate-share-assets-url: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+            };
+        }
+    }
+    /**
+     * POST /digital-assets/collection/generate-share-url
+     *
+     * Source: Admin-Frontend
+     * `components/dam/Dialogs/ShareAssetDialog/index.vue:520`. Body shape:
+     *
+     *   { workspace_id, id (collection id), assets: number[], title?, description?,
+     *     password?, hide_download?: 0|1, expiration?: 'MMM D, YYYY' }
+     */
+    async generateCollectionShareUrl(input) {
+        const body = {
+            workspace_id: this.workspaceId,
+            id: input.collection_id,
+            assets: input.assets,
+            title: input.title ?? '',
+            description: input.description ?? null,
+        };
+        if (input.password !== undefined)
+            body['password'] = input.password;
+        if (input.hide_download !== undefined)
+            body['hide_download'] = input.hide_download;
+        if (input.expiration !== undefined)
+            body['expiration'] = input.expiration;
+        const raw = await this.post('digital-assets/collection/generate-share-url', { body });
+        if (!raw.ok)
+            return raw;
+        try {
+            const parsed = unwrapEnvelope(raw.data, GenerateShareLinkResponseSchema);
+            return { ok: true, data: parsed, request_id: raw.request_id };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', `Schema mismatch on collection/generate-share-url: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+            };
+        }
+    }
+    /**
+     * GET /digital-assets/dashboard/list-share-assets-url
+     *
+     * Source: Admin-Frontend
+     * `pages/_workspace_id/dam/sharing/index.vue:784`. Query shape:
+     *
+     *   { workspace_id, page, total_record, filter_by?, sort_value?, sort_by? }
+     *
+     * Returns a Laravel paginator under `data`. `filter_by` accepts
+     * Admin-Frontend values like `'active'`, `'expired'`, `'revoked'`.
+     */
+    async listShareLinks(input) {
+        // `filter_by` is REQUIRED by upstream — omitting it returns HTTP 400
+        // "The filter by field is required." (verified live 2026-04-29).
+        // Admin-Frontend defaults to 'active'; mirror that. Callers can override.
+        const query = {
+            workspace_id: this.workspaceId,
+            page: input.page,
+            total_record: input.pageSize,
+            sort_by: input.sortBy ?? 'DESC',
+            sort_value: input.sortValue ?? 'created_at',
+            filter_by: input.filterBy ?? 'active',
+        };
+        const raw = await this.get('digital-assets/dashboard/list-share-assets-url', { query });
+        if (!raw.ok)
+            return raw;
+        try {
+            const parsed = unwrapEnvelope(raw.data, ShareLinkListEnvelopeSchema);
+            return { ok: true, data: parsed, request_id: raw.request_id };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', `Schema mismatch on list-share-assets-url: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+            };
+        }
+    }
+    /**
+     * Read a single share link by id (client-side filter over
+     * `listShareLinks`). Used for the revoke preview so the dry-run plan
+     * can show `before` state.
+     */
+    async getShareLink(shareId) {
+        const list = await this.listShareLinks({ page: 1, pageSize: 200 });
+        if (!list.ok)
+            return list;
+        const target = String(shareId);
+        const match = list.data.data.find((row) => String(row.id) === target);
+        if (match === undefined) {
+            return {
+                ok: false,
+                request_id: list.request_id,
+                error: createToolError('NOT_FOUND', `Share link ${shareId} not found in workspace.`, { cause: { request_id: list.request_id } }),
+            };
+        }
+        return { ok: true, data: match, request_id: list.request_id };
+    }
+    /**
+     * POST /digital-assets/dashboard/delete-share-assets-url
+     *
+     * Source: Admin-Frontend
+     * `pages/_workspace_id/dam/sharing/index.vue:1059`. Body shape:
+     *
+     *   { workspace_id, share_url_id: number[] }
+     *
+     * The Admin-Frontend reuses this endpoint for both single-id and
+     * `revoke-all` flows; only the multi-id bulk endpoint
+     * (`delete-multiple-share-assets-url`) uses `share_url_ids`. We use
+     * the single-id path because `revoke_share_link` is a one-at-a-time tool.
+     */
+    async revokeShareLink(shareId) {
+        const raw = await this.post('digital-assets/dashboard/delete-share-assets-url', {
+            body: {
+                workspace_id: this.workspaceId,
+                share_url_id: [shareId],
+            },
+        });
+        if (!raw.ok)
+            return raw;
+        const parsed = SimpleMessageEnvelopeSchema.safeParse(raw.data);
+        const message = parsed.success ? parsed.data.message : undefined;
+        return {
+            ok: true,
+            request_id: raw.request_id,
+            data: message !== undefined ? { message } : {},
+        };
+    }
+    /**
+     * GET /digital-assets/{id}/generate-embed-code
+     *
+     * Source: Admin-Frontend
+     * `components/dam/Dialogs/ShareAssetDialog/index.vue:476`. Read-only
+     * (the upstream caches and returns a stable embed snippet for the asset).
+     * Response shape: `{ data: { embed_code: '<iframe...>' } }`.
+     */
+    async generateEmbedCode(assetId) {
+        const raw = await this.get(`digital-assets/${encodeURIComponent(String(assetId))}/generate-embed-code`);
+        if (!raw.ok)
+            return raw;
+        try {
+            const parsed = unwrapEnvelope(raw.data, GenerateEmbedCodeResponseSchema);
+            return { ok: true, data: parsed, request_id: raw.request_id };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', `Schema mismatch on generate-embed-code: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+            };
+        }
+    }
+    /**
+     * Internal helper: GET + zod-parse using `unwrapEnvelope` so callers can
+     * pass either the bare-array shape or `{ status, message, data: [...] }`.
+     */
+    async parsedGet(path, schema, options) {
+        const raw = await this.get(path, options);
+        if (!raw.ok)
+            return raw;
+        try {
+            const parsed = unwrapEnvelope(raw.data, schema);
+            return { ok: true, data: parsed, request_id: raw.request_id };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                request_id: raw.request_id,
+                error: createToolError('UPSTREAM', `Schema mismatch on ${path}: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+            };
+        }
+    }
+    buildUrl(path, options) {
+        const cleanedPath = path.replace(/^\/+/, '');
+        const url = new URL(cleanedPath, this.baseUrl);
+        if (options?.scoped !== false) {
+            url.searchParams.set('url_workspace_id', this.workspaceId);
+        }
+        if (options?.query) {
+            for (const [key, value] of Object.entries(options.query)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+    async request(method, path, options) {
+        const requestId = generateRequestId();
+        const url = this.buildUrl(path, options);
+        const childLog = this.log.child({ request_id: requestId, method, path });
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+            'X-Request-Id': requestId,
+        };
+        if (options?.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const fetchOnce = async () => {
+            await this.limiter.acquire();
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), options?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            try {
+                const init = {
+                    method,
+                    headers,
+                    signal: controller.signal,
+                };
+                if (options?.body !== undefined) {
+                    init.body = JSON.stringify(options.body);
+                }
+                const response = await fetch(url, init);
+                if (!response.ok) {
+                    const retryAfterMs = parseRetryAfter(response.headers.get('Retry-After'));
+                    const text = sanitizeUpstreamBody(await safeReadText(response));
+                    if (response.status === 429 || (response.status >= 500 && response.status < 600)) {
+                        const opts = {
+                            statusCode: response.status,
+                        };
+                        if (retryAfterMs !== undefined) {
+                            opts.retryAfterMs = retryAfterMs;
+                        }
+                        throw new RateLimitedError(`Upstream ${response.status}: ${text}`, opts);
+                    }
+                    // Non-retriable HTTP error — wrap with the status so the outer
+                    // handler can map it to an MCP error code.
+                    throw new HttpError(response.status, text);
+                }
+                if (response.status === 204) {
+                    return undefined;
+                }
+                const contentType = response.headers.get('Content-Type') ?? '';
+                if (!contentType.includes('application/json')) {
+                    // Non-JSON success bodies are surfaced as text.
+                    return (await response.text());
+                }
+                return (await response.json());
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        };
+        try {
+            const data = await withRetry(fetchOnce);
+            childLog.debug('collage request ok');
+            return { ok: true, data, request_id: requestId };
+        }
+        catch (err) {
+            const error = mapToToolError(err, requestId);
+            childLog.warn({ err: serialiseErr(err), code: error.code }, 'collage request failed');
+            return { ok: false, error, request_id: requestId };
+        }
+    }
+}
+class HttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'HttpError';
+    }
+}
+function parseRetryAfter(header) {
+    if (header === null || header === '')
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1000;
+    }
+    const date = Date.parse(header);
+    if (!Number.isNaN(date)) {
+        const ms = date - Date.now();
+        return ms > 0 ? ms : 0;
+    }
+    return undefined;
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '';
+    }
+}
+const UPSTREAM_BODY_MAX_CHARS = 512;
+/**
+ * Strip credential-shaped substrings and clamp length before an upstream
+ * body is interpolated into an `McpToolError.message` (which is visible
+ * to the LLM client). Defensive — production Collage responses do not
+ * echo credentials, but custom middleware or debug builds could.
+ *
+ * The `X-Amz-Signature=` redaction handles presigned S3 URLs returned
+ * in `view-detail` responses. A presigned URL with a 24h expiry is a
+ * bearer-equivalent for the asset until it expires; leaking the
+ * signature into a logged error or LLM-visible message is the same
+ * risk class as leaking a token.
+ */
+function sanitizeUpstreamBody(text) {
+    if (text === '')
+        return text;
+    const scrubbed = text
+        .replace(/Bearer\s+[A-Za-z0-9._-]+/gi, 'Bearer [REDACTED]')
+        .replace(/eyJ[A-Za-z0-9._-]{20,}/g, '[REDACTED_JWT]')
+        .replace(/(api[_-]?key|token|secret)\s*[:=]\s*"?[A-Za-z0-9._-]{8,}"?/gi, '$1=[REDACTED]')
+        .replace(/X-Amz-Signature=[^&\s"'<>]+/gi, 'X-Amz-Signature=[REDACTED]');
+    return scrubbed.length > UPSTREAM_BODY_MAX_CHARS
+        ? `${scrubbed.slice(0, UPSTREAM_BODY_MAX_CHARS)}…`
+        : scrubbed;
+}
+function mapToToolError(err, requestId) {
+    if (err instanceof HttpError) {
+        return createToolError(mapHttpStatusToErrorCode(err.status), err.message, {
+            cause: { upstream_status: err.status, request_id: requestId },
+        });
+    }
+    if (err instanceof RateLimitedError) {
+        return createToolError(mapHttpStatusToErrorCode(err.statusCode), err.message, {
+            cause: { upstream_status: err.statusCode, request_id: requestId },
+        });
+    }
+    if (err instanceof Error && err.name === 'AbortError') {
+        return createToolError('UPSTREAM', 'Request timed out', {
+            cause: { request_id: requestId },
+        });
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return createToolError('INTERNAL', message, { cause: { request_id: requestId } });
+}
+function serialiseErr(err) {
+    if (err instanceof Error) {
+        return { name: err.name, message: err.message };
+    }
+    return { value: String(err) };
+}
+// ── Collection-mutation response helpers ─────────────────────────────
+// The collection write endpoints return either an envelope
+// (`{ status, message, data: { id, name, description, ... } }`) or — on some
+// older routes — the row directly. We extract the canonical fields
+// defensively so a missing `description` is normalised to `null`.
+const CollectionMutationDataSchema = z.object({
+    id: z.union([z.number(), z.string()]).optional(),
+    name: z.string().optional(),
+    description: z.string().nullable().optional(),
+}).passthrough();
+function parseCollectionMutationResponse(raw, fallbackId) {
+    try {
+        const data = unwrapEnvelope(raw.data, CollectionMutationDataSchema);
+        const id = data.id ?? fallbackId;
+        if (id === undefined) {
+            throw new Error('response omitted id and no fallback was provided');
+        }
+        return {
+            ok: true,
+            request_id: raw.request_id,
+            data: {
+                id,
+                name: data.name ?? '',
+                description: data.description ?? null,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            request_id: raw.request_id,
+            error: createToolError('UPSTREAM', `Schema mismatch on collection mutation: ${err instanceof Error ? err.message : String(err)}`, { cause: { request_id: raw.request_id } }),
+        };
+    }
+}
+function extractMessage(raw) {
+    if (raw !== null && typeof raw === 'object' && 'message' in raw) {
+        const msg = raw.message;
+        if (typeof msg === 'string')
+            return msg;
+    }
+    return undefined;
+}
+/**
+ * Pulls the new folder id out of a `category/add` or
+ * `category/add-sub-category` response. Tolerates both top-level `id` and
+ * the more common `data.id` shape.
+ */
+function extractCreatedCategoryId(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const candidates = [obj['id']];
+    const data = obj['data'];
+    if (data !== null && typeof data === 'object') {
+        candidates.push(data['id']);
+    }
+    for (const c of candidates) {
+        if (typeof c === 'number' && Number.isFinite(c))
+            return c;
+        if (typeof c === 'string' && c.length > 0)
+            return c;
+    }
+    return null;
+}
+//# sourceMappingURL=client.js.map