@collage-dam/mcp-server 0.1.0

package/dist/tools/client-adapters.js

@@ -0,0 +1,648 @@
+// ── Tool Client Adapters ─────────────────────────────────────────────
+// Each Phase 1 mutating tool declares a narrow client interface it needs
+// (rename, metadata read/write, tag read/write, collection metadata
+// read/write, single-collection membership read). This module wires those
+// interfaces to live `CollageClient` methods.
+//
+// Read paths reuse `getAssetDetails` (POST view-detail) where possible so
+// we avoid duplicating round-trips for the same data. Custom-field reads
+// fan out to `getAssetCustomFields` because `view-detail` does not include
+// the custom-field projection in the same shape the metadata tool needs.
+//
+// The lone exception is `searchAssets` (Typesense-backed) — that adapter
+// stays UPSTREAM-stubbed until the public Typesense host is provisioned.
+import { createToolError } from '../conventions/errors.js';
+import { generateRequestId } from '../conventions/logger.js';
+import { runSearchAssets } from './search/search-assets.js';
+import { ENUMERATOR_HARD_CAP, } from './insights/analyze-share-links.js';
+// ── Asset Enumerator (audit_tagging_hygiene) ─────────────────────────
+/**
+ * Backed by `CollageClient.enumerateAssets()` which iterates folders via
+ * `view-files-with-category`. Workspace-wide flat enumeration is otherwise
+ * Typesense-only.
+ *
+ * Returns a typed `UPSTREAM` error if folder listing 402s (current
+ * BREZ-workspace state) — the audit tool surfaces that to the caller as
+ * a structured failure instead of an empty result.
+ */
+export function buildAssetEnumerator(client) {
+    return {
+        enumerateAssets: async () => {
+            const res = await client.enumerateAssets();
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true, assets: res.data.map((a) => ({ id: a.id, tags: a.tags })) };
+        },
+    };
+}
+/** Helper for tests / future swap-in: enumerator backed by an in-memory list. */
+export function fixedAssetEnumerator(assets) {
+    return {
+        enumerateAssets: async () => ({ ok: true, assets: [...assets] }),
+    };
+}
+// ── Search adapter (selection 'query' path) ──────────────────────────
+/**
+ * Default unavailable adapter — kept for tests and for the
+ * pre-Typesense-provisioned mode.
+ */
+export function buildSearchAdapter(_client) {
+    return {
+        searchAssets: async () => ({
+            ok: false,
+            error: createToolError('UPSTREAM', 'Asset search is not available: the public Typesense host has not ' +
+                'been provisioned yet. Use `ids` or `collection_id` selection.'),
+        }),
+    };
+}
+/**
+ * Search adapter backed by the Collage Nuxt search proxy. Bridges the
+ * bulk-tag tools' `AssetSearchAdapter` interface to the workspace-scoped
+ * `search_assets` runner. Returns up to the first page (per_page=250) of
+ * hits, projected down to the `ResolvedAsset` shape expected by the
+ * resolver. The `tags` array is only present when the index actually
+ * has tags indexed for the row — empty when the indexer has not yet
+ * caught up.
+ */
+export function buildTypesenseSearchAdapter(searchClient, workspaceId) {
+    return {
+        searchAssets: async (query) => {
+            const requestId = generateRequestId();
+            const result = await runSearchAssets(searchClient, workspaceId, {
+                q: query,
+                page: 1,
+                per_page: 250,
+                sort_by: '_text_match:desc,modified_at:desc',
+                projection: 'verbose',
+            }, requestId);
+            if (result.isError === true) {
+                const sc = result.structuredContent;
+                const err = sc.error ?? { code: 'UPSTREAM', message: 'unknown search failure', retriable: true };
+                return { ok: false, error: createToolError(err.code, err.message) };
+            }
+            const sc = result.structuredContent;
+            const assets = [];
+            for (const hit of sc.hits) {
+                const asset = { id: String(hit.id) };
+                if (hit.display_file_name !== null && hit.display_file_name !== undefined) {
+                    asset.display_file_name = hit.display_file_name;
+                }
+                if (Array.isArray(hit.tags)) {
+                    asset.tags = hit.tags;
+                }
+                assets.push(asset);
+            }
+            return { ok: true, assets };
+        },
+    };
+}
+// ── rename_asset client ──────────────────────────────────────────────
+export function buildRenameAssetClient(client) {
+    return {
+        getCurrentName: async (assetId) => {
+            const res = await client.getAssetDetails(assetId);
+            if (!res.ok)
+                return null;
+            const name = res.data.display_file_name;
+            return name === '' ? null : name;
+        },
+        renameAsset: async (assetId, newName) => {
+            const res = await client.renameAsset(assetId, newName);
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true };
+        },
+    };
+}
+// ── update_asset_metadata client ─────────────────────────────────────
+/**
+ * `view-detail` carries `display_file_name` and `description` directly. We
+ * map `display_file_name` onto the tool's `title` slot (the
+ * Admin-Frontend rename UI does the same — there is no separate "title"
+ * column in `digital_assets`).
+ *
+ * Custom fields come from a separate `get-custom-fields` call, projected
+ * by `name` (with `field_name` as fallback) into `Record<string, CustomFieldValue>`.
+ * Update side: we re-fetch the same projection, overwrite each `value` for
+ * the requested keys, and POST the full array back via `update-custom-fields`.
+ */
+export function buildUpdateAssetMetadataClient(client) {
+    return {
+        getMetadata: async (assetId) => {
+            const detail = await client.getAssetDetails(assetId);
+            if (!detail.ok)
+                return { ok: false, error: detail.error };
+            const fields = await client.getAssetCustomFields(assetId);
+            const customFields = fields.ok
+                ? projectCustomFieldsToValues(fields.data)
+                : {};
+            const snapshot = {
+                title: snapshotTitle(detail.data),
+                description: detail.data.description ?? null,
+                custom_fields: customFields,
+            };
+            return { ok: true, snapshot };
+        },
+        updateMetadata: async (assetId, patch) => {
+            const errors = [];
+            if (patch.title !== undefined) {
+                const r = await client.updateAssetField(assetId, 'display_file_name', patch.title);
+                if (!r.ok)
+                    errors.push(r.error);
+            }
+            if (patch.description !== undefined) {
+                const r = await client.updateAssetField(assetId, 'description', patch.description);
+                if (!r.ok)
+                    errors.push(r.error);
+            }
+            if (patch.custom_fields !== undefined) {
+                // Re-fetch the projection so we can overwrite values by name and
+                // round-trip the full row shape the upstream expects.
+                const current = await client.getAssetCustomFields(assetId);
+                if (!current.ok) {
+                    errors.push(current.error);
+                }
+                else {
+                    const updated = mergeCustomFieldUpdates(current.data, patch.custom_fields);
+                    const r = await client.updateAssetCustomFields(assetId, updated);
+                    if (!r.ok)
+                        errors.push(r.error);
+                }
+            }
+            if (errors.length > 0) {
+                const first = errors[0];
+                if (first === undefined) {
+                    return {
+                        ok: false,
+                        error: createToolError('INTERNAL', 'metadata update failed without a specific error'),
+                    };
+                }
+                return { ok: false, error: first };
+            }
+            return { ok: true };
+        },
+    };
+}
+function snapshotTitle(detail) {
+    const name = detail.display_file_name;
+    return name === '' ? null : name;
+}
+function projectCustomFieldsToValues(fields) {
+    const out = {};
+    for (const f of fields) {
+        const key = f.name ?? f.field_name;
+        if (key === undefined)
+            continue;
+        out[key] = coerceToCustomFieldValue(f.value);
+    }
+    return out;
+}
+function coerceToCustomFieldValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const arr = [];
+        for (const v of value) {
+            if (typeof v === 'string' || typeof v === 'number')
+                arr.push(v);
+        }
+        return arr;
+    }
+    // Fall back to JSON string so the diff renderer has *something* to show.
+    return JSON.stringify(value);
+}
+function mergeCustomFieldUpdates(current, patch) {
+    return current.map((f) => {
+        const key = f.name ?? f.field_name;
+        const next = key !== undefined && key in patch ? patch[key] : undefined;
+        if (next === undefined) {
+            // Untouched — pass through the row as the upstream expects.
+            return { ...f };
+        }
+        return { ...f, value: next };
+    });
+}
+// ── bulk_*_tags client ───────────────────────────────────────────────
+/**
+ * Tag read uses `view-detail.tags` (array of `{id, tag_name}`). Write side:
+ * `setTags` is a full-replace — diff against current, add new via
+ * `add-tags-to-multiple-file`, remove others via
+ * `delete-tag-from-multiple-file` (called once per removed tag because the
+ * upstream takes a single `tag_name` per request).
+ */
+export function buildBulkTagsClient(client) {
+    return {
+        getCurrentTags: async (assetId) => {
+            const res = await client.getAssetDetails(assetId);
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            const names = (res.data.tags ?? []).map((t) => t.tag_name);
+            return { ok: true, tags: names };
+        },
+        setTags: async (assetId, tags) => {
+            const current = await client.getAssetDetails(assetId);
+            if (!current.ok)
+                return { ok: false, error: current.error };
+            const currentNames = (current.data.tags ?? []).map((t) => t.tag_name);
+            const wanted = new Set(tags);
+            const have = new Set(currentNames);
+            const toAdd = tags.filter((t) => !have.has(t));
+            const toRemove = currentNames.filter((t) => !wanted.has(t));
+            if (toAdd.length > 0) {
+                const r = await client.addTagsToAssets([assetId], toAdd);
+                if (!r.ok)
+                    return { ok: false, error: r.error };
+            }
+            for (const name of toRemove) {
+                const r = await client.removeTagFromAssets([assetId], name);
+                if (!r.ok)
+                    return { ok: false, error: r.error };
+            }
+            return { ok: true };
+        },
+    };
+}
+// ── create_collection client ─────────────────────────────────────────
+export function buildCreateCollectionClient(client) {
+    return {
+        createCollection: async (input) => {
+            const res = await client.createCollection({
+                name: input.name,
+                description: input.description,
+            });
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true, collection_id: String(res.data.id) };
+        },
+        addAssetsToCollection: async (collectionId, assetIds) => {
+            const res = await client.addAssetsToCollection(collectionId, assetIds);
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true };
+        },
+    };
+}
+// ── update_collection client ─────────────────────────────────────────
+export function buildUpdateCollectionClient(client) {
+    return {
+        getCollectionMetadata: async (collectionId) => {
+            // CollageClient exposes listCollections; locate the target by id.
+            const res = await client.listCollections();
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            const match = res.data.find((c) => String(c.id) === collectionId);
+            if (match === undefined) {
+                return {
+                    ok: false,
+                    error: createToolError('NOT_FOUND', `Collection ${collectionId} not found in workspace.`),
+                };
+            }
+            return {
+                ok: true,
+                snapshot: {
+                    name: match.name ?? null,
+                    description: match.description ?? null,
+                },
+            };
+        },
+        updateCollectionMetadata: async (collectionId, patch) => {
+            const res = await client.updateCollection(collectionId, patch);
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true };
+        },
+    };
+}
+// ── add/remove_to_collection client ──────────────────────────────────
+export function buildCollectionMembershipClient(client) {
+    return {
+        getCollectionAssetIds: async (collectionId) => {
+            const res = await client.listCollections();
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            const match = res.data.find((c) => String(c.id) === collectionId);
+            if (match === undefined) {
+                return {
+                    ok: false,
+                    error: createToolError('NOT_FOUND', `Collection ${collectionId} not found in workspace.`),
+                };
+            }
+            const ids = (match.assets_id ?? []).map((id) => String(id));
+            return { ok: true, asset_ids: ids };
+        },
+        addAssetsToCollection: async (collectionId, assetIds) => {
+            const res = await client.addAssetsToCollection(collectionId, assetIds);
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true };
+        },
+        removeAssetsFromCollection: async (collectionId, assetIds) => {
+            const res = await client.removeAssetsFromCollection(collectionId, assetIds);
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true };
+        },
+    };
+}
+export function buildCreateShareLinkClient(client) {
+    return {
+        createShareLink: async (request) => {
+            // Map the dry-run-resolved request to the right upstream endpoint:
+            // collection target → POST collection/generate-share-url,
+            // asset target     → POST dashboard/generate-share-assets-url.
+            const sharedFields = {
+                title: request.title,
+                description: request.description,
+                password: request.password,
+                hide_download: request.hide_download,
+                expiration: request.expiration,
+            };
+            if (request.target_kind === 'collection' && request.collection_id !== undefined) {
+                const res = await client.generateCollectionShareUrl({
+                    collection_id: request.collection_id,
+                    assets: request.asset_ids,
+                    ...sharedFields,
+                });
+                if (!res.ok)
+                    return { ok: false, error: res.error };
+                return {
+                    ok: true,
+                    share_id: String(res.data.id),
+                    share_url: res.data.share_url,
+                };
+            }
+            const res = await client.generateShareAssetsUrl({
+                assets: request.asset_ids,
+                category: [],
+                ...sharedFields,
+            });
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return {
+                ok: true,
+                share_id: String(res.data.id),
+                share_url: res.data.share_url,
+            };
+        },
+    };
+}
+// ── revoke_share_link client ─────────────────────────────────────────
+export function buildRevokeShareLinkClient(client) {
+    return {
+        getShareLink: async (shareId) => {
+            const res = await client.getShareLink(shareId);
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            const row = res.data;
+            const password = row.password;
+            const passwordProtected = typeof password === 'string' && password.length > 0;
+            const snapshot = {
+                id: String(row.id),
+                title: row.title ?? null,
+                share_url: row.share_url ?? row.share_new_url ?? null,
+                expiration: row.expiration ?? null,
+                password_protected: passwordProtected,
+            };
+            return { ok: true, snapshot };
+        },
+        revokeShareLink: async (shareId) => {
+            const res = await client.revokeShareLink(shareId);
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true };
+        },
+    };
+}
+// ── create_folder / rename_folder / move_asset clients ───────────────
+export function buildCreateFolderClient(client) {
+    return {
+        createFolder: async (input) => {
+            const res = await client.createCategory({
+                folder_name: input.folder_name,
+                parent_id: input.parent_id,
+            });
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true, folder_id: String(res.data.id) };
+        },
+    };
+}
+export function buildRenameFolderClient(client) {
+    return {
+        getCurrentFolderName: async (categoryId) => {
+            const list = await client.listAllCategoriesRecursive();
+            if (!list.ok)
+                return null;
+            const found = list.data.find((c) => String(c.id) === categoryId);
+            return found?.folder_name ?? null;
+        },
+        renameFolder: async (input) => {
+            const renameInput = {
+                folder_name: input.folder_name,
+            };
+            if (input.description !== undefined) {
+                renameInput.description = input.description;
+            }
+            const res = await client.renameCategory(input.category_id, renameInput);
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true };
+        },
+    };
+}
+export function buildMoveAssetClient(client) {
+    return {
+        moveAsset: async (input) => {
+            const res = await client.moveAssetsAndFolders({
+                asset_ids: [input.asset_id],
+                folder_ids: [],
+                destination_id: input.destination_category_id,
+            });
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            return { ok: true };
+        },
+    };
+}
+// ── analyze_share_links enumerator ───────────────────────────────────
+//
+// Walks `client.listShareLinks` once per status bucket
+// (active / expired / revoked) so each row can be tagged with its
+// upstream-derived status. Pages until the upstream paginator is
+// exhausted or the internal cap (`ENUMERATOR_HARD_CAP`) is hit. When
+// the cap is reached, the partial dataset is returned with
+// `truncated: true`; the analyzer surfaces that to the caller as
+// `report.truncated` so downstream renderers can flag the partial
+// result.
+//
+// Why per-status fetches: the live `ShareLink` schema does not expose a
+// `status` column; the only way to discriminate active vs expired vs
+// revoked is to query each upstream `filter_by` value separately. This
+// fans out to three list calls per analysis — acceptable for the read-
+// only use case and easily memoized by the T5 cache layer.
+const SHARE_LINK_PAGE_SIZE = 200;
+export function buildShareLinkAnalyticsEnumerator(client) {
+    return {
+        enumerate: async () => {
+            const statuses = ['active', 'expired', 'revoked'];
+            const collected = [];
+            let truncated = false;
+            let lastError = null;
+            let anyOk = false;
+            for (const status of statuses) {
+                if (collected.length >= ENUMERATOR_HARD_CAP) {
+                    truncated = true;
+                    break;
+                }
+                let page = 1;
+                // Per-status pagination loop.
+                // eslint-disable-next-line no-constant-condition
+                while (true) {
+                    const res = await client.listShareLinks({
+                        page,
+                        pageSize: SHARE_LINK_PAGE_SIZE,
+                        filterBy: status,
+                    });
+                    if (!res.ok) {
+                        // Track per-status failures so a single 4xx (e.g. 'revoked'
+                        // unsupported) does not mask successful status fetches. If
+                        // every status fails, surface the last error.
+                        lastError = res.error;
+                        break;
+                    }
+                    anyOk = true;
+                    const rows = res.data.data;
+                    for (const row of rows) {
+                        if (collected.length >= ENUMERATOR_HARD_CAP) {
+                            truncated = true;
+                            break;
+                        }
+                        collected.push(projectShareLinkToRow(row, status));
+                    }
+                    if (truncated)
+                        break;
+                    // Stop when we've reached the last page or the upstream
+                    // returned fewer rows than the requested page size.
+                    const lastPage = res.data.last_page;
+                    if (lastPage !== undefined && page >= lastPage)
+                        break;
+                    if (rows.length < SHARE_LINK_PAGE_SIZE)
+                        break;
+                    page += 1;
+                }
+                if (truncated)
+                    break;
+            }
+            if (!anyOk && lastError !== null) {
+                return { ok: false, error: lastError };
+            }
+            return { ok: true, rows: collected, truncated };
+        },
+    };
+}
+function projectShareLinkToRow(row, status) {
+    // `total_visited` may be number | string | null per upstream schema.
+    const viewCountRaw = row.total_visited;
+    let viewCount = 0;
+    if (typeof viewCountRaw === 'number' && Number.isFinite(viewCountRaw)) {
+        viewCount = viewCountRaw;
+    }
+    else if (typeof viewCountRaw === 'string') {
+        const parsed = Number(viewCountRaw);
+        if (Number.isFinite(parsed))
+            viewCount = parsed;
+    }
+    const assetIds = (row.asset_ids ?? []).map((id) => String(id));
+    // `ShareLink` does not yet model `collection_id` — it's a passthrough
+    // field. Read it defensively without a runtime cast to `any`.
+    const collectionIdRaw = row['collection_id'];
+    const collectionId = typeof collectionIdRaw === 'string' || typeof collectionIdRaw === 'number'
+        ? String(collectionIdRaw)
+        : null;
+    // `expiration` is the upstream's expires_at field (string | null).
+    const expiresAt = typeof row.expiration === 'string' && row.expiration.length > 0
+        ? row.expiration
+        : null;
+    const createdAt = typeof row.created_at === 'string' && row.created_at.length > 0
+        ? row.created_at
+        : null;
+    const userId = row.user_id;
+    const createdByUserId = typeof userId === 'string' || typeof userId === 'number'
+        ? String(userId)
+        : null;
+    return {
+        id: String(row.id),
+        title: typeof row.title === 'string' ? row.title : null,
+        share_url: typeof row.share_url === 'string' && row.share_url.length > 0
+            ? row.share_url
+            : typeof row.share_new_url === 'string' && row.share_new_url.length > 0
+                ? row.share_new_url
+                : null,
+        view_count: viewCount,
+        created_at: createdAt,
+        expires_at: expiresAt,
+        status,
+        created_by_user_id: createdByUserId,
+        asset_ids: assetIds,
+        collection_id: collectionId,
+    };
+}
+// ── report_asset_activation dashboard reader ─────────────────────────
+//
+// `getDashboardCommonData()` returns `unknown` at the client layer. The
+// reader narrows it through a small zod schema covering only the fields
+// the activation report consumes. When the parse fails (i.e. the
+// upstream shape changes or the workspace is in a degraded state that
+// returns a different envelope), the reader returns `ok: true,
+// snapshot: null` so the report can degrade gracefully to
+// `total_assets: null` rather than failing.
+import { z } from 'zod';
+/**
+ * Narrow projection of `dashboard/common-data`. The upstream envelope
+ * carries dozens of opaque keys; we only require `total_assets` to be a
+ * non-negative integer. Several plausible field names are accepted to
+ * tolerate small upstream renames (the live Admin-Frontend reads either
+ * `total_assets` or `total_record` depending on the dashboard widget).
+ */
+const DashboardCommonDataSchema = z
+    .object({
+    total_assets: z.number().int().nonnegative().optional(),
+    total_record: z.number().int().nonnegative().optional(),
+    data: z
+        .object({
+        total_assets: z.number().int().nonnegative().optional(),
+        total_record: z.number().int().nonnegative().optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+export function buildDashboardCommonDataReader(client) {
+    return {
+        read: async () => {
+            const res = await client.getDashboardCommonData();
+            if (!res.ok)
+                return { ok: false, error: res.error };
+            const parsed = DashboardCommonDataSchema.safeParse(res.data);
+            if (!parsed.success) {
+                // Shape regressed — surface as null so the report can degrade.
+                return { ok: true, snapshot: null };
+            }
+            const total = parsed.data.total_assets ??
+                parsed.data.total_record ??
+                parsed.data.data?.total_assets ??
+                parsed.data.data?.total_record ??
+                null;
+            if (total === null)
+                return { ok: true, snapshot: null };
+            const snapshot = { total_assets: total };
+            return { ok: true, snapshot };
+        },
+    };
+}
+//# sourceMappingURL=client-adapters.js.map