@collage-dam/mcp-server 0.1.0

package/dist/typesense.js.map

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

package/docs/api-field-verification.md

@@ -0,0 +1,244 @@
+# Collage API Field Verification — Reference
+
+> **Last updated 2026-05-04**
+
+Canonical reference for every field-name / payload-shape mismatch the
+MCP server has discovered between the live Collage API and the public
+Swagger spec. Ships with the deployment runbook as a Week-6 handoff
+deliverable.
+
+## Why this exists
+
+The published Collage Swagger covers ~30 endpoints; the live frontend uses 150+. Naive consumers will hit silent-failure or 400-error walls. Every field name, payload shape, and response envelope captured below is verified two ways: (1) against the Admin-Frontend source (cited per row), and (2) by a live contract test against workspace `1927483178` (BREZ).
+
+## How to use this
+
+If you're adding a CollageClient method:
+
+1. **Find the Admin-Frontend call site** — use `grep -rn "<endpoint>" Admin-Frontend` to locate it. The frontend is the source of truth.
+2. **Mirror its payload shape exactly**. Don't trust Swagger; trust the frontend.
+3. **Add a contract test** in `tests/contract/<endpoint>.contract.test.ts` that hits BREZ live and asserts the response shape.
+4. **If you find a new mismatch**, append to this doc under the matching section.
+
+If you're consuming a CollageClient method: it already absorbs every quirk listed here. The Zod-validated `ClientResult<T>` contract is stable.
+
+## Verified mismatches
+
+### Asset endpoints
+
+#### `POST /digital-assets/view-detail`
+- **Quirk**: body uses `digital_assets_id` (NOT `asset_id`).
+- **Source**: `Admin-Frontend/pages/_workspace_id/dam/files/_id.vue` (passim).
+- **Code**: `CollageClient.getAssetDetails()` (`src/client.ts`).
+- **Contract test**: `tests/contract/get-asset-details.contract.test.ts`.
+
+#### `POST /digital-assets/update-with-field`
+- **Quirk**: body requires `digital_assets_id` (NOT `asset_id`) AND `workspace_id` AND the global `?url_workspace_id=` query — three workspace identifiers in three places.
+- **Body shape**: `{ workspace_id, digital_assets_id, field_name, field_value }`.
+- **Source**: `pages/_workspace_id/dam/files/_id.vue:2329`, `components/dam/SearchAssets.vue:1206`.
+- **Code**: `CollageClient.updateAssetField()`, `renameAsset()` (the rename flow uses `field_name: 'display_file_name'`).
+
+#### `GET /digital-assets/get-custom-fields`
+- **Quirk**: requires `workspace_id` in the query in addition to the global `?url_workspace_id=` (different param name). Missing → HTTP 400 "Validation is failed."
+- **Query shape**: `{ asset_id, workspace_id }`.
+- **Source**: `pages/_workspace_id/dam/files/_id.vue:1319`.
+- **Code**: `CollageClient.getAssetCustomFields()`.
+
+#### `POST /digital-assets/update-custom-fields`
+- **Quirk**: uses `asset_ids` (plural) even when updating one asset; `updated_data` is the FULL row projection (id, name, value, …) — not a partial patch.
+- **Body shape**: `{ workspace_id, asset_ids: [id], updated_data: [{ id, value, … }] }`.
+- **Source**: `pages/_workspace_id/dam/files/_id.vue:2894`.
+- **Code**: `CollageClient.updateAssetCustomFields()`.
+
+### Tag endpoints
+
+#### `POST /digital-assets/add-tags-to-multiple-file`
+- **Body shape**: `{ workspace_id, digital_assets_ids: [id, …], tags: ['name', …] }`.
+- **`tags`** is an array of plain string names — the upstream creates new tag rows on demand.
+- **Source**: `components/dam/AssetList/AddTags.vue:86`.
+- **Code**: `CollageClient.addTagsToAssets()`.
+
+#### `POST /digital-assets/delete-tag-from-multiple-file`
+- **Quirk**: TWO payload shapes depending on caller.
+  - **Single-asset**: uses `tag_id`.
+  - **Multi-asset (or full-replace)**: uses `tag_name`, `digital_assets_ids` is an array of `{ id }` *objects*.
+- **Body shape (multi)**: `{ workspace_id, digital_assets_ids: [{ id }, …], tag_name }`.
+- **Source**: `components/dam/Dialogs/AddTags/AddMultipleTags.vue:202`.
+- **Code**: `CollageClient.removeTagFromAssets()` — uses the multi shape.
+
+#### `POST /digital-assets/get-common-tag-list`
+- **Quirk**: NOT a workspace-wide tag listing. Returns the *intersection* of tags across a given `asset_ids` list.
+- **Body shape**: `{ workspace_id, asset_ids }`.
+- **Source**: `Backend-API/.../TagController.php:499`, `Admin-Frontend/components/dam/Dialogs/AddTags/AddMultipleTags.vue:295`.
+- **Effect**: blocks `collage://tags` resource (no workspace-wide endpoint). Tracked in `mcp-resources` spec backlog.
+
+### Folder / category endpoints
+
+#### `POST /digital-assets/category/add` and `category/add-sub-category`
+- **Quirk**: TWO endpoints, distinguished by the body — top-level uses `add`, nested uses `add-sub-category` AND adds the parent's id under the **misnamed `category_id` key** (not `parent_id`).
+- **Body shapes**:
+  - Top-level: `{ workspace_id, folder_name }` → `category/add`
+  - Nested: `{ workspace_id, folder_name, category_id: parentId }` → `category/add-sub-category`
+- **Source**: `components/dam/Dialogs/miniUploadBackdrop.vue:358,366`.
+- **Code**: `CollageClient.createCategory()` — picks the path based on `parent_id`.
+
+#### `POST /digital-assets/category/rename/{id}`
+- **Body shape**: `{ workspace_id, folder_name, description? }`.
+- **Source**: `pages/_workspace_id/dam/folders/index.vue:1281`.
+- **Code**: `CollageClient.renameCategory()`.
+
+#### `POST /digital-assets/multiple-file-folder-move`
+- **Quirk**: keys are `assets_ids`, `category_ids`, and `move_id` — NOT `asset_ids`/`folder_ids`/`destination_id` as a clean API would suggest. `move_id` accepts `null` for the uncategorised root.
+- **Body shape**: `{ workspace_id, assets_ids: number[], category_ids: number[], move_id: destFolderId | null }`.
+- **Source**: `components/dam/Dialogs/FolderDialogs/FolderDialog.vue:1471`.
+- **Code**: `CollageClient.moveAssetsAndFolders()`.
+
+#### `GET /digital-assets/category/all-category-list`
+- **Quirk**: returns ROOT-LEVEL folders only — the upstream is flat-by-design. To traverse, walk `sub-category-list` per parent.
+- **Code**: `CollageClient.listCategories()` for roots; `CollageClient.listAllCategoriesRecursive()` for the full tree (FU3, 2026-05-04).
+- **Source**: `pages/_workspace_id/dam/folders/index.vue:999-1008`.
+
+#### `GET /digital-assets/category/sub-category-list`
+- **Query shape**: `{ workspace_id, category_id }`.
+- **Source**: `components/dam/Dialogs/FolderDialogs/FolderDialog.vue:758`.
+- **Code**: `CollageClient.listSubCategories()`.
+
+#### `GET /digital-assets/category/view-files-with-category`
+- **Quirk**: returns Laravel paginator nested as `data.assets_with_folder.{data, last_page, total}`, NOT a flat `data` array. Each row in `assets_with_folder.data` is the raw `digital_assets` row, NOT the `view-detail` projection (no joined tags).
+- **Query shape**: `{ workspace_id, category_id, page, sort_by, sort_value }`.
+- **Source**: `pages/_workspace_id/dam/folders/_id/index.vue:3357`.
+- **Code**: `CollageClient.listAssetsByCategory()`.
+
+#### Workspace-id requirements (global)
+- Every read endpoint requires the `?url_workspace_id=` query AND most also require `workspace_id` in the body or query — root cause of the original 402 critical (resolved 2026-05-01). Ross confirmed this is by design; the frontend always sends both.
+
+### Collection endpoints
+
+#### `GET /digital-assets/collection/get-all`
+- **Quirk**: response includes the FULL asset detail objects in `collage_assets`, not just IDs.
+- **Code**: `CollageClient.listCollections()`, `getCollection()`.
+
+#### `POST /digital-assets/collection/update/{id}`
+- **Quirk**: response payload omits `id` at the top level on BREZ. The path id is the canonical identity; client falls back to it.
+- **Body shape**: `{ name?, description? }`.
+- **Code**: `CollageClient.updateCollection()`.
+
+#### `POST /digital-assets/collection/{id}/add-assets` and `remove-assets`
+- **Quirk**: body uses `assets_id` (singular noun with trailing `s`, NOT `asset_ids`).
+- **Body shape**: `{ assets_id: (string|number)[] }`.
+- **Code**: `CollageClient.addAssetsToCollection()`, `removeAssetsFromCollection()`.
+
+### Share-link endpoints
+
+#### `POST /digital-assets/dashboard/generate-share-assets-url`
+- **Quirk**: body uses `assets` (NOT `asset_ids`) and `category` (NOT `folder_ids`).
+- **Body shape**: `{ workspace_id, assets: number[], category: number[], title?, description?, password?, hide_download?: 0|1, expiration?: 'MMM D, YYYY' }`.
+- **Source**: `components/dam/Dialogs/ShareAssetDialog/index.vue:399`.
+- **Code**: `CollageClient.generateShareAssetsUrl()`.
+
+#### `POST /digital-assets/collection/generate-share-url`
+- **Body shape**: `{ workspace_id, id (collection id), assets: number[], title?, description?, password?, hide_download?: 0|1, expiration?: 'MMM D, YYYY' }`.
+- **Source**: `components/dam/Dialogs/ShareAssetDialog/index.vue:520`.
+- **Code**: `CollageClient.generateCollectionShareUrl()`.
+
+#### `expiration` format
+- **Quirk**: sent as `'MMM D, YYYY'`-formatted string (e.g. `'May 4, 2026'`). Admin-Frontend uses `moment(...).format('MMM D, YYYY')`.
+- **Code**: our share-link tool accepts ISO 8601 input and translates internally.
+
+#### `GET /digital-assets/dashboard/list-share-assets-url`
+- **Quirk**: `filter_by` is REQUIRED. Omitting it returns HTTP 400 "The filter by field is required." Admin-Frontend defaults to `'active'`.
+- **Query shape**: `{ workspace_id, page, total_record, filter_by, sort_value?, sort_by? }`.
+- **Valid `filter_by` values**: `'active'`, `'expired'`, `'revoked'`.
+- **Source**: `pages/_workspace_id/dam/sharing/index.vue:784`.
+- **Code**: `CollageClient.listShareLinks()` defaults `filter_by` to `'active'`.
+
+#### `POST /digital-assets/dashboard/delete-share-assets-url`
+- **Quirk**: single-id revoke uses `share_url_id` (singular key, **array value**). Bulk uses a different endpoint (`delete-multiple-share-assets-url`) with `share_url_ids` (plural key).
+- **Body shape (single)**: `{ workspace_id, share_url_id: number[] }`.
+- **Source**: `pages/_workspace_id/dam/sharing/index.vue:1059`.
+- **Code**: `CollageClient.revokeShareLink()`.
+
+### Embed-code endpoints
+
+#### `GET /digital-assets/{id}/generate-embed-code`
+- **Quirk**: asset-only — there is **no collection-level embed endpoint**. `Admin-Frontend`'s `getEmbedLink` only operates on asset ids.
+- **Code**: `CollageClient.generateEmbedCode()`.
+
+### Search endpoint
+
+#### `POST app.collage.inc/typesense/search` (Nuxt proxy, not Laravel)
+- **Quirk #1 — different host**: lives on `app.collage.inc`, not `damapi.collage.inc`. The Laravel host serves no `/typesense*` path.
+- **Quirk #2 — workspace_id resolution**: the proxy receives the DB workspace id (e.g. `1927483178`) in the body, then resolves it to the **`workspace_unique_id`** (e.g. `178`) by hitting Laravel's `/user` endpoint with the inbound Bearer token. The Typesense documents store the unique_id under the `workspace_id` field. Client-side filter clauses MUST NOT prepend `workspace_id:=<DB-id>` — that double-ANDs against the proxy's `workspace_id: <unique_id>` clause and zero-outs results.
+- **Quirk #3 — facet_by stripped**: the Nuxt middleware drops `facet_by` and `max_facet_values` before forwarding to Typesense. `facet_counts` always returns `[]` regardless of request shape. Tracked in `nuxt-search-proxy-strips-facet-by-05-04-2026.md`.
+- **Quirk #4 — auth**: the proxy verifies the inbound `Authorization: Bearer <token>` header against `${API_BASE_URL}user`. Our existing `COLLAGE_API_KEY` works as the token (no separate Typesense key needed).
+- **Source**: `Admin-Frontend/api/typesense.js`.
+- **Code**: `src/typesense.ts` — `createCollageSearchClient()`, `searchWorkspaceScoped()`.
+
+### Visibility / type values
+
+#### Visibility numeric (NOT string)
+- `0` = public
+- `1` = private
+- The MCP server passes the numeric form through unchanged. Consumers (LLMs) read Collage's native shape.
+
+#### File type strings
+- File type values are stored as the file extension stripped of leading dot: `'png'`, `'mp4'`, `'pdf'`. Not MIME types.
+
+#### `is_archive`, `is_deleted`, `final_deleted`
+- All are `0|1` flags (numeric, not boolean).
+
+#### `category_id` on assets
+- **`category_id` IS the folder ID.** Naming inconsistency carried through from the original DB schema (folders are stored in `digital_assets_categories`).
+
+## Workspace ID format gotcha
+
+| Where used | Format | Example |
+|---|---|---|
+| `?url_workspace_id=` (every request) | full DB id | `1927483178` |
+| `workspace_id` in bodies/queries | full DB id | `1927483178` |
+| Inside Typesense indexed documents | `workspace_unique_id` | `178` |
+| `workspace_unique_id` field on `accessibleWorkspaces` | unique id | `178` |
+
+The Nuxt search proxy bridges the two formats server-side via `/user` lookup.
+
+## What our tests cover
+
+The contract test suite (`tests/contract/`) hits every wired endpoint live against BREZ on every `INTEGRATION=1` run:
+
+- `get-asset-details.contract.test.ts` — `view-detail` shape.
+- `list-categories.contract.test.ts` — `all-category-list`.
+- `list-collections.contract.test.ts` — `collection/get-all`.
+- `list-embed-codes.contract.test.ts` — `embed-code-list`.
+- `enumerate-assets.contract.test.ts` — `view-files-with-category`.
+- `folder-tools.contract.test.ts` — `list_categories`, `view_category_contents`.
+- `unblocked-endpoints.contract.test.ts` — `sub-category-list`, `instance/get`, `dashboard/common-data`, `get-recent-uploaded`.
+- `share-link.contract.test.ts` — `list-share-assets-url`, `generate-share-assets-url`.
+- `check-workspace-access.contract.test.ts` — `check-workspace-access`.
+- `resources.contract.test.ts` — every wired MCP resource (12 tests).
+- `search.contract.test.ts` — Nuxt `/typesense/search` proxy (added 2026-05-04).
+- `asset-write.contract.test.ts` + `collection-mutations.contract.test.ts` — write-side; conditional on workspace state.
+
+**As of 2026-05-04: 34 contract tests pass live against BREZ. Any new field-name surprise will fail a contract test, not become a runtime bug.**
+
+## Open mismatches NOT yet absorbed
+
+None at the time of writing. Three resources blocked on UPSTREAM endpoint design (not field-name) issues are tracked separately in the `mcp-resources` spec backlog:
+
+- `collage://tags` — no workspace-wide endpoint exists.
+- `collage://analytics` — only per-asset analytics exists.
+- `collage://portals/{id}/users` — endpoint TBD.
+
+## Maintenance
+
+When adding a new endpoint to `CollageClient`:
+
+1. Cite the Admin-Frontend source line in the docstring.
+2. Add a contract test under `tests/contract/<endpoint>.contract.test.ts`.
+3. Append to the appropriate section above.
+4. If the endpoint exposes a NEW class of quirk, add a new section.
+
+When a contract test starts failing after an upstream change:
+
+1. Diff the response against the schema. Update the schema if the change is benign.
+2. If the change is a breaking field rename, update the client, update the docstring, and append a "Resolved" note to this doc with the date.
+3. Bump `updated:` in the frontmatter.