@antelopejs/dms-media 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,218 +1,91 @@
1
- # @antelopejs/dms-media
2
-
3
1
  <div align="center">
4
- <a href="https://www.npmjs.com/package/@antelopejs/dms-media"><img alt="NPM version" src="https://img.shields.io/npm/v/@antelopejs/dms-media.svg?style=for-the-badge&labelColor=000000"></a>
5
- <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge&labelColor=000000"></a>
6
- <a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
7
- <a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
8
- </div>
9
-
10
- AntelopeJS DMS module providing an asset/media library: upload, folders, delivery derivatives and light image editing, with per-folder permissions that reuse the DMS authorization system. Ships a Finder-style file explorer (frontend) and an `AssetType` field to reference library assets from forms.
11
-
12
- See [AGENTS.md](../../AGENTS.md) for code conventions.
13
-
14
- ## Installation
15
-
16
- ```bash
17
- ajs project modules add @antelopejs/dms-media
18
- ```
19
2
 
20
- ## Features
21
-
22
- - **Folder tree with per-folder ACL** — a linked folder carries the ACL (`AclEntry[]`) its binding derives, every other folder inherits from its parent (root falls back to the configurable `rootAcl`, which grants nothing by default). Entries grant `read`/`write`/`manage` rights to either a **permission id** (anyone holding e.g. `articles.page.table.edit`) or a **role id**. Rights imply weaker ones (`manage ⇒ write ⇒ read`). Ancestors of a readable folder are returned as **traverse-only shells** (name visible, content never listed).
23
- - **Single data path** — listing, search, picker and delivery all resolve the same `readable`/`writable`/`manageable` sets per request; nothing bypasses the ACL.
24
- - **Direct-to-storage uploads** — `presign` (type and quota checks, staged) → client `PUT` → `confirm` (type check again, sharp decode of declared images, promote + DB row). Bytes never transit through Node. The stored mimetype is the one sharp reads, and the dimensions follow the EXIF orientation. `abort` deletes a staged file, and an hourly cron deletes the ones never confirmed.
25
- - **Stable delivery URLs** — `GET /media/:assetId/:filename` 302-redirects to a signed storage URL. The redirect itself is never cached (`Cache-Control: no-cache` for public assets, with `Access-Control-Allow-Origin: *`; `no-store` for private ones, after auth + folder read check), so an edit or a visibility change shows on the next request; the signed URL it points to is reused for half its lifetime. A link with a stale file name redirects to the canonical one. Active content is the exception: SVG (inline) and HTML, XHTML and XML files (as `attachment`) are served by the API itself with `Content-Security-Policy: sandbox`, `X-Content-Type-Options: nosniff`, ETag/304 and Range support. A browser that opens a private file without a token is redirected to the file's page in the dashboard (`/modules/media/file?asset=`), which signs in and comes back; when the dashboard URL is unknown it gets a 401 HTML page. Visibility (asset override → folder → private) is a flag flip; URLs never change.
26
- - **Lazy image derivatives** — named presets (config) rendered by sharp on first request, cached in storage under a config-hashed cache key, served via `GET /media/:assetId/:presetId/:filename` and the authenticated `read-url` endpoint. Changing a preset invalidates naturally (new hash); a daily cron sweeps stale keys. An image sharp cannot read answers 422, a size that fails to render for another reason 503.
27
- - **Server-side image editing** — `transform` (normalized crop, 90° rotations) overwrites the image everywhere it is used, `transform/copy` saves the edit as a new file next to the untouched source ("Save as copy"), and `revert` restores the original. The pristine original is preserved on first edit (its size counts in the storage), successive edits are rendered from it, and derivatives are invalidated.
28
- - **`AssetType` form field** — registers the `asset` data type whose widget (`DmsMediaAssetPicker`) opens the Finder as a picker. Declaring a `binding` auto-provisions a linked folder under the `Content` root (idempotency key = binding id) whose ACL derives from the declared permission mapping; linked folders cannot be renamed, moved, deleted or re-ACLed through the API.
29
- - **Media module** — registered with `RegisterModule` like every DMS module, so it is listed under Modules and its pages live under `/modules/media` (they are the owner's administration of the library, see [Access model](#access-model)): Library (Overview `/modules/media/overview`, Library `/modules/media/files`, Uploads `/modules/media/uploads`, plus the hidden File `/modules/media/file?asset=`, Edit image `/modules/media/editor?asset=` and Activity `/modules/media/activity` pages) and Settings (Image sizes `/modules/media/presets`). Every page is a backend block tree. Module pages are owner-only (see [Static permissions](#static-permissions)).
30
- - **Explorer** — server-paged listings with facets (type, visibility, modification date, orientation), smart views (recents, starred, missing alt text, largest, public), server search over names, alt text and folders (accents, case and word order ignored), bulk move/visibility/delete, zip download of a selection or of a folder with its subfolders, drag and drop, keyboard shortcuts and a shared upload queue that survives navigation.
31
- - **Unique names** — renaming a file, or creating, renaming or moving a folder, onto a name its folder already holds (case and Unicode form aside) answers 409, and an upload that collides offers "Keep both" (the next free name, `photo (2).jpg`, from `POST /api/media/upload/names`) or "Cancel". A name typed in the library that Windows or macOS cannot save is refused, a subfolder cannot be created in or moved into a linked folder (403), and validation errors answer `$dms_media.errors.*` keys the dashboard translates.
32
- - **Activity** — every write is recorded in `media_events` (kept 90 days) and feeds the overview, the Activity page (filterable by kind of action), the file history and the upload batches.
3
+ # @antelopejs/dms-media
33
4
 
34
- ## Static permissions
5
+ <a href="https://www.npmjs.com/package/@antelopejs/dms-media"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/dms-media?style=for-the-badge&labelColor=000000&color=000000"></a>
6
+ <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/dms-media?style=for-the-badge&labelColor=000000&color=000000"></a>
7
+ <a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
8
+ <a href="https://dms.antelopejs.com/docs/modules/media"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
35
9
 
36
- The module registers no permission: nothing about media is offered in Settings › Roles, because the Media pages are owner-only and members reach media through the project's pages (see [Access model](#access-model)).
10
+ A media library for the AntelopeJS DMS: uploads, folders, image sizes and light editing.
37
11
 
38
- | Permission | Effect |
39
- |---|---|
40
- | `modules.media.library.files` | Page permission of Library. Like every module page permission it is owner-only: it is not listed in Roles and `HasPermission` refuses it to any non-owner. It grants no folder right |
12
+ </div>
41
13
 
42
- Per-folder rights are the single authority for operations: upload requires `write` on the target folder, folder structure changes require `manage`. The owner holds every right on every folder. Changing a file or folder visibility is owner-only.
14
+ ![The Media library explorer: views and folders on the left, the files of a folder in the middle, the selected file's details on the right](https://raw.githubusercontent.com/AntelopeJS/dms-media/main/packages/dms-media/docs/images/library.png)
43
15
 
44
- ## Access model
16
+ ## What it does
45
17
 
46
- The module's pages are the **owner's administration** of the library: like the pages of every DMS module they are owner-only, on purpose, and cannot be given to a role.
18
+ - Organises images, videos and documents in a Finder-style explorer, with smart views, search, drag and drop and bulk actions.
19
+ - Uploads files straight to the project's file storage and delivers them from stable `/media/<id>/<name>` URLs.
20
+ - Renders named image sizes on first request, with crop and rotation that can revert to the original.
21
+ - Applies per-folder rights built on the DMS permissions and roles.
22
+ - Adds an `AssetType` form field, from [`@antelopejs/interface-dms-media`](https://github.com/AntelopeJS/dms-media/tree/main/packages/interface-dms-media), that opens the library as a picker on your pages.
47
23
 
48
- Members use media **through the component the module exports**: an `AssetType` field placed on the **project's** pages, which are grantable in Settings › Roles. The field opens the "floating" picker and uploader on a folder defined in advance: its `binding` provisions a linked folder, and `permissionsFromPage` derives that folder's rights from the project page that holds the field. A member whose role grants the page can see the linked folder and upload into it from the picker, without ever opening a Media page:
24
+ ## Install
49
25
 
50
- ```ts
51
- @RegisterPage()
52
- export class ArticlesPage extends PageController("articles", { displayName: "Articles", category: pagesCategory }) {
53
- static form = Form({
54
- fields: [
55
- {
56
- id: "cover",
57
- label: "Cover",
58
- type: new AssetType({
59
- mimetypes: ["image/*"],
60
- binding: { id: "articles.cover", folderName: "Article covers", permissionsFromPage: ArticlesPage },
61
- }),
62
- },
63
- ],
64
- });
65
- }
66
- ```
26
+ Run the AntelopeJS CLI from the root of a project that already loads `@antelopejs/dms` and a file storage module:
67
27
 
68
- The page permission must be an explicit grant of the role: a page every member opens by default (`memberAccess`, `publicAccess`) grants no folder right, because folder ACL subjects match the permissions a member holds. In a linked folder, the member can upload, describe, rename, move, delete and edit every file of the folder, whoever added it; making a file public or private stays with the owner. The rest of the library stays closed to members: the default root ACL grants nothing, and only a permission or role a project adds to `rootAcl`, opens it to the picker.
69
-
70
- ## Module configuration
71
-
72
- ```json
73
- {
74
- "dms-media": {
75
- "config": {
76
- "storage": "media",
77
- "rootAcl": [{ "subject": { "kind": "permission", "id": "articles.page" }, "rights": ["read"] }],
78
- "allowedMimetypes": ["image/*", "application/pdf"],
79
- "storageQuotaBytes": 10000000000,
80
- "publicBaseUrl": "${@api.API_PUBLIC_BASE_URL}",
81
- "presets": [
82
- { "id": "thumb", "width": 300, "height": 300, "fit": "cover", "format": "webp", "quality": 80 }
83
- ]
84
- }
85
- }
86
- }
28
+ ```bash
29
+ ajs project modules add @antelopejs/dms-media
87
30
  ```
88
31
 
89
- All keys are optional:
90
-
91
- - `storage` selects a named `interface-file-storage` backend (default storage otherwise).
92
- - `rootAcl` sets the rights every folder without its own ACL inherits. The default is empty: owners hold every right anyway, and members only reach the linked folders of their pages. An entry you add here opens the whole library to its subject.
93
- - `allowedMimetypes` lists the file types the library accepts (`image/*` matches a prefix). The default is `image/*`, `video/*`, `audio/*`, `application/pdf`, the Office types (`application/msword`, `application/vnd.ms-excel`, `application/vnd.ms-powerpoint`, `application/vnd.openxmlformats-officedocument.*`), OpenDocument (`application/vnd.oasis.opendocument.*`), `application/rtf`, `text/plain`, `text/markdown` and `text/csv`. HTML, XHTML and PHP (`text/html`, `application/xhtml+xml`, the PHP types, and `.htm`, `.html`, `.xhtml`, `.xht`, `.shtml`, `.mht`, `.mhtml`, `.php`, `.php3`–`.php8`, `.phps`, `.pht`, `.phtml`, `.phar` files) are always refused, whatever the list says.
94
- - `storageQuotaBytes` sets the storage plan: the overview measures usage against it, and `presign` refuses an upload that would go past it.
95
- - `publicBaseUrl` is the public URL of the API, the origin serving `/media/...`: "Copy link" in the library and the links of the file page's Delivery tab start with it. Point it at the api module's public base URL (`"${@api.API_PUBLIC_BASE_URL}"`, as `file-storage-local`'s `baseUrl`). Without it, links start with the DMS `apiBaseUrl` (`GetApiBaseUrl`), and stay relative when neither is set; request headers (`Host`, `X-Forwarded-*`) are never read. Links do not use the dashboard's origin: it only relays non-HTML requests to `/media`, so a link opened in a tab would end on its 404.
96
- - `presets` replaces the default `thumb`/`preview` presets. Keep a `thumb` preset — the Finder uses it for grid thumbnails.
97
-
98
- A refused upload answers a JSON body `{ "reason": …, "message": … }` the upload queue explains in the member's language: `type_not_allowed` (415, not an accepted type), `field_type` (415, the linked folder feeds a field that accepts fewer types, listed in `accepted`), `quota` (413, the storage plan is full, with `remaining` and `quota`) or `invalid_image` (422 on `confirm`, a declared image that does not decode).
32
+ ## Quick start
99
33
 
100
- Two crons run with the module: `dms-media-purge-staging`, every hour, deletes the uploads staged more than 24 hours ago and never confirmed, and a daily sweep removes stale derivatives.
34
+ Point the module's links at the API's public URL, and allow the dashboard's origin, since the browser uploads straight to the storage:
101
35
 
102
- ## Deployment: allow the dashboard's origin
103
-
104
- Files do not go through the dashboard. The browser asks the API to `presign` the upload, then `PUT`s the file straight to the URL the storage returns: with `file-storage-local`, its `baseUrl`, the API's public URL (`${@api.API_PUBLIC_BASE_URL}/file-storage/...`). That is another origin than the dashboard's, so the api module must list every origin the dashboard is served on in `cors.allowedOrigins`:
105
-
106
- ```json
107
- {
108
- "api": {
109
- "config": {
110
- "cors": {
111
- "allowedOrigins": ["https://dms.example.com", "http://dms.localhost:3014"]
112
- }
113
- }
114
- },
115
- "file-storage-local": {
116
- "config": { "baseUrl": "${@api.API_PUBLIC_BASE_URL}" }
117
- }
118
- }
36
+ ```ts
37
+ // antelope.config.ts
38
+ "dms-media": {
39
+ source: { type: "package", package: "@antelopejs/dms-media", version: "^0.4.0" },
40
+ config: {
41
+ publicBaseUrl: "${@api.API_PUBLIC_BASE_URL}",
42
+ },
43
+ },
44
+ api: {
45
+ config: {
46
+ cors: { allowedOrigins: ["https://dms.example.com"] },
47
+ },
48
+ },
119
49
  ```
120
50
 
121
- Without it, the browser blocks the `PUT` (its console shows a CORS error on `/file-storage/...`) while listing and presigning still work. The upload queue, the AssetType field and the toasts then say the storage refused this site's address, naming the origin to add; retrying cannot help until it is allowed. When the storage address itself cannot be reached from the browser (an internal host name as `baseUrl`, for instance), they say so instead: point `baseUrl`, and the module's `publicBaseUrl`, at the public URL of the API.
122
-
123
- ## Declaring an AssetType field
124
-
125
- `AssetType` and the folder bindings it declares live in the interface package [`@antelopejs/interface-dms-media`](../interface-dms-media), which this module implements. Declare the interface in the consumer module's `dependencies` and import from it:
126
-
127
- ```bash
128
- pnpm add @antelopejs/interface-dms-media
129
- ```
51
+ Restart the backend, then the frontend, and open **Modules › Media** (`/modules/media/overview`). To let members pick files from your own pages, add an asset field:
130
52
 
131
53
  ```ts
132
54
  import { AssetType } from "@antelopejs/interface-dms-media";
133
55
 
134
56
  new AssetType({
135
- multiple: true,
136
- max: 4,
137
- mimetypes: ["image/*"],
138
- binding: {
139
- id: "articles.cover",
140
- folderName: "Article covers",
141
- permissionMapping: {
142
- read: ["articles.page"],
143
- write: ["articles.page.table.edit", "articles.page.table.add"],
144
- },
145
- },
57
+ mimetypes: ["image/*"],
58
+ binding: { id: "articles.cover", folderName: "Article covers", permissionsFromPage: ArticlesPage },
146
59
  });
147
60
  ```
148
61
 
149
- When the field lives on a DMS page, `permissionsFromPage` derives the mapping from that page's effective permission instead of duplicating its id — pass the page class itself (`permissionsFromPage: ArticlesPage`); resolution happens lazily at folder provisioning, and explicit `permissionMapping` entries still win per right (an empty array opts that right out of the fallback).
150
-
151
- A `binding` is registered through `RegisterAssetBinding` (also exported by the interface, together with `UnregisterAssetBinding`). The registration belongs to the module that declares the field: it is released when that module is destroyed, and replayed to dms-media whenever dms-media reloads.
152
-
153
- ## HTTP surface
154
-
155
- - Library: `GET /api/media/tree` (folders, plus `allowedMimetypes`), `GET /api/media/folders/:id/assets|impact`, `GET /api/media/views/:view` (`recent`, `starred`, `missing-alt`, `largest`, `public`), `GET /api/media/search` (an empty `q` finds nothing), `POST /api/media/favorites`, `POST /api/media/folders/starter`. Folder listings and views take the `type`, `visibility`, `modified` and `orientation` facets; views also take a `folderId` to stay inside one folder
156
- - Overview (owners only, 403 otherwise): `GET /api/media/stats/kpis|storage|attention|recent`, `GET /api/media/activity?type=`
157
- - File: `GET /api/media/assets/:id/details|history|information|delivery|delivery/notice|tab-counts`, `GET /api/media/links/origin` (the origin copied links start with: `publicBaseUrl`, otherwise the DMS `apiBaseUrl`)
158
- - Bulk: `POST /api/media/assets/bulk/move|visibility|delete`, `POST /api/media/assets/zip`, `POST /api/media/folders/:id/zip` (the folder and its subfolders, `read` right)
159
- - Settings: `GET|POST /api/media/upload/batches`, `GET /api/media/presets`, `GET /api/media/presets/config`, `GET /api/media/presets/cache`
160
- - `POST /api/media/folders`, `POST /api/media/folders/:id/rename|move|visibility`, `DELETE /api/media/folders/:id`
161
- - `GET /api/media/assets`, `GET /api/media/assets/search`, `GET /api/media/assets/:id`, `GET /api/media/assets/:id/read-url?preset=`, `POST /api/media/previews`
162
- - `POST /api/media/assets/:id/update|move|visibility|transform|transform/copy|revert`, `DELETE /api/media/assets/:id`
163
- - Upload: `POST /api/media/upload/presign`, `POST /api/media/upload/confirm`, `POST /api/media/upload/abort` (deletes the staged file), `POST /api/media/upload/names` (free names for "Keep both")
164
- - Public delivery: `GET /media/:assetId/:filename`, `GET /media/:assetId/:presetId/:filename`
165
-
166
- `GET /api/media/stats/folders` and `GET /api/media/stats/largest` are removed: the overview no longer shows folder cards or the largest files, which the `largest` view lists.
167
-
168
- Status codes worth handling:
169
-
170
- | Route | Status | Body |
171
- |---|---|---|
172
- | `upload/presign` | 415 | `{ reason: "type_not_allowed", message }`: not in `allowedMimetypes`, or HTML/XHTML/PHP (by type or extension) |
173
- | `upload/presign` | 415 | `{ reason: "field_type", message, accepted }`: the linked folder feeds a field that accepts fewer types |
174
- | `upload/presign` | 413 | `{ reason: "quota", message, remaining, quota }`: the upload would go past `storageQuotaBytes` |
175
- | `upload/confirm` | 422 | `{ reason: "invalid_image", message }`: a declared image that does not decode; the staged file is deleted |
176
- | `assets/:id/update`, `folders`, `folders/:id/rename|move` | 409 | `$dms_media.errors.name_taken` or `folder_name_taken`: the name is taken in that folder, case aside |
177
- | `folders`, `folders/:id/move` | 403 | `$dms_media.errors.bound_parent`: the parent is a linked folder |
178
- | Folder, file and bulk writes | 400 | A `$dms_media.errors.*` key |
179
- | `/media/:assetId/:filename` | 302 | To the signed storage URL (`no-cache` public, `no-store` private), to the canonical file name, or, for a browser without a token on a private file, to the dashboard's File page |
180
- | `/media/:assetId/:filename` | 401 | Private file without a token: bare for scripts, an HTML page for a browser when the dashboard URL is unknown |
181
- | `/media/:assetId/:presetId/:filename` | 422 / 503 | The image cannot be read / the size cannot be rendered right now |
182
-
183
- ## Development
184
-
185
- The module lives in `packages/dms-media` of a pnpm workspace, next to the interface package it implements (`packages/interface-dms-media`). Run these from `packages/dms-media`:
186
-
187
- ```bash
188
- pnpm install # whole workspace; the interface resolves to the sibling package
189
- pnpm build # builds the interface, then the module
190
- pnpm dev # backend, via playground (ajs project run -w -p playground)
191
- pnpm frontend:dev # Vue 3 Inertia frontend, from playground (ajs dms dev)
192
- pnpm test # build + full mocha suite (unit + HTTP integration)
193
- pnpm test:unit # build + unit tests only (no HTTP)
194
- pnpm test:reload # hot reload of a consumer and of the module, in a real project
195
- ```
62
+ ## Compatibility
196
63
 
197
- The playground is a project of its own, outside the workspace: install it with `pnpm --dir playground install --ignore-workspace` before `pnpm dev`. It links `@antelopejs/interface-dms-media` from `packages/interface-dms-media`, and `pnpm dev` builds the interface, the module and the playground in that order before starting the backend.
64
+ | Package | Version |
65
+ | --- | --- |
66
+ | `@antelopejs/dms` | `>=0.9.0 <1.0.0` |
67
+ | `@antelopejs/interface-dms` | `>=0.7.0 <1.0.0` |
68
+ | `@antelopejs/dms-frontend` (renderer) | `>=0.6.0 <0.7.0` |
69
+ | `@antelopejs/interface-dms-media` | `>=0.2.1 <0.3.0` |
70
+ | File storage | an `@antelopejs/interface-file-storage` implementation, such as `@antelopejs/file-storage-local` |
198
71
 
199
- The playground's Media demo page (`/media-demo`) holds every flavour of the `AssetType` picker: a single cover image with a linked folder, a gallery with a maximum, a PDF-only spec sheet, documents restricted to PDF, Word and text files in their own linked folder, and a free attachment.
72
+ On DMS 0.8, use `@antelopejs/dms-media` 0.3.
200
73
 
201
- The playground connects to MongoDB at `mongodb://localhost:27017` by default. Set `MONGO_URL` to point it at another instance, e.g. `MONGO_URL=mongodb://127.0.0.1:27019 pnpm dev`.
74
+ ## Documentation
202
75
 
203
- The frontend entry is `frontend-vue/dms.frontend.ts`. It declares `componentPrefix: "DmsMedia"` and registers the blocks of `app/components/*.vue` by file name (`Explorer` is served as `DmsMediaExplorer`); the parts in subfolders are imported by path. `dms.frontend.build.ts` auto-imports `app/composables` and `app/utils`. Use relative imports for module-local files because the Inertia adapter copies the frontend separately from the backend. The adapter discovers locale files and `app/config/shortcuts-registry.ts`; no Nuxt installation is required.
76
+ - [Introduction](https://dms.antelopejs.com/docs/modules/media/introduction)
77
+ - [Installation](https://dms.antelopejs.com/docs/modules/media/installation)
78
+ - [Configuration](https://dms.antelopejs.com/docs/modules/media/configuration)
79
+ - [Usage](https://dms.antelopejs.com/docs/modules/media/usage/overview)
80
+ - [Extending](https://dms.antelopejs.com/docs/modules/media/extending)
81
+ - [FAQ](https://dms.antelopejs.com/docs/modules/media/faq)
204
82
 
205
- The blocks read the data they render with the DMS's `useApiData` (`@antelopejs/dms` 0.9, `@antelopejs/interface-dms` 0.7, `@antelopejs/dms-frontend` 0.6): a server render reads it and hands it to the browser with the page. The explorer's folder tree is the same read, and its file listing one `useApiPagedData` read keyed by the location and the filters ("Load more" appends a page, a library change reads every loaded page again). The reads that follow the library's realtime changes on their own opt out of the page's refreshes. Writes, downloads, and the reads of the asset field's entries, the dialogs and the image editor's canvas, stay `$authFetch` calls in the browser.
83
+ The guide's sources live in [`packages/dms-media/docs`](https://github.com/AntelopeJS/dms-media/tree/main/packages/dms-media/docs). The module ships the `dms-media` Claude Code skill in [`packages/dms-media/skills`](https://github.com/AntelopeJS/dms-media/tree/main/packages/dms-media/skills), declared under `antelopeJs.skills`.
206
84
 
207
- The file links (`/media/<id>/<name>`) are served by the backend. The module declares `/media/**` as a backend prefix (`backendProxies`, with the session), so that a link on the dashboard's origin reaches the backend and a private file opens for a signed-in member.
85
+ ## Contributing
208
86
 
209
- The playground uses the `@antelopejs/dms-frontend` CLI. Run `pnpm --dir frontend-vue install` and `pnpm --dir frontend-vue test` for frontend tests; `tests/serverRender.test.ts` renders the blocks on the server with the renderer and the DMS layer the package installs. `pnpm test:frontend` typechecks the layer against the DMS layer (`ajs dms verify-source`), without a running backend; CI runs it.
87
+ This package lives in the [`AntelopeJS/dms-media`](https://github.com/AntelopeJS/dms-media) pnpm workspace, next to `@antelopejs/interface-dms-media`. Read [CONTRIBUTING.md](https://github.com/AntelopeJS/dms-media/blob/main/CONTRIBUTING.md) and the [repository README](https://github.com/AntelopeJS/dms-media#contributing) for the development commands.
210
88
 
211
- ## Known limitations (v1)
89
+ ## License
212
90
 
213
- - Abandoned staged uploads are purged from the `media_uploads` table the module fills at `presign` (`interface-file-storage` exposes no listing).
214
- - The DMS invite flow does not expose invite tokens over HTTP (see the DMS module's `TESTING.md`), so the multi-user HTTP integration tests seed their invites straight into the database (`src/test/helpers/members.ts`).
215
- - Folder visibility applies to the folder's direct assets (no recursive visibility inheritance); assets inherit or override individually.
216
- - Cover cropping is centred (no focal point), and reference counting ("used in N records") is not supported yet.
217
- - The `AssetType` field has no crop button: editing an image changes it everywhere it is used, and a crop per usage comes later.
218
- - Replacing a file, a trash for deleted files and the server-side validation of `AssetType` values are not there yet; each comes in its own release.
91
+ [Apache-2.0](./LICENSE)
@@ -15,6 +15,7 @@ declare const MediaAssetModel_base: {
15
15
  delete(id: string): Promise<number>;
16
16
  };
17
17
  readonly schemaName: string;
18
+ readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<MediaAsset>;
18
19
  fromPlainData(obj: any): MediaAsset;
19
20
  fromDatabase(obj: any): MediaAsset | undefined;
20
21
  toDatabase(obj: any): Record<string, any>;
@@ -12,6 +12,7 @@ declare const MediaEventModel_base: {
12
12
  delete(id: string): Promise<number>;
13
13
  };
14
14
  readonly schemaName: string;
15
+ readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<MediaEvent>;
15
16
  fromPlainData(obj: any): MediaEvent;
16
17
  fromDatabase(obj: any): MediaEvent | undefined;
17
18
  toDatabase(obj: any): Record<string, any>;
@@ -12,6 +12,7 @@ declare const MediaFavoriteModel_base: {
12
12
  delete(id: string): Promise<number>;
13
13
  };
14
14
  readonly schemaName: string;
15
+ readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<MediaFavorite>;
15
16
  fromPlainData(obj: any): MediaFavorite;
16
17
  fromDatabase(obj: any): MediaFavorite | undefined;
17
18
  toDatabase(obj: any): Record<string, any>;
@@ -12,6 +12,7 @@ declare const MediaFolderModel_base: {
12
12
  delete(id: string): Promise<number>;
13
13
  };
14
14
  readonly schemaName: string;
15
+ readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<MediaFolder>;
15
16
  fromPlainData(obj: any): MediaFolder;
16
17
  fromDatabase(obj: any): MediaFolder | undefined;
17
18
  toDatabase(obj: any): Record<string, any>;
@@ -12,6 +12,7 @@ declare const MediaUploadModel_base: {
12
12
  delete(id: string): Promise<number>;
13
13
  };
14
14
  readonly schemaName: string;
15
+ readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<MediaUpload>;
15
16
  fromPlainData(obj: any): MediaUpload;
16
17
  fromDatabase(obj: any): MediaUpload | undefined;
17
18
  toDatabase(obj: any): Record<string, any>;
@@ -99,7 +99,7 @@ exports.default = (0, config_1.defineConfig)({
99
99
  source: {
100
100
  type: "package",
101
101
  package: "@antelopejs/dms",
102
- version: ">=0.9.0 <1.0.0",
102
+ version: ">=0.9.3 <1.0.0",
103
103
  },
104
104
  config: {
105
105
  auth: {
@@ -111,7 +111,7 @@ exports.default = (0, config_1.defineConfig)({
111
111
  source: {
112
112
  type: "package",
113
113
  package: "@antelopejs/mongodb",
114
- version: "1.4.2",
114
+ version: "1.4.3",
115
115
  },
116
116
  },
117
117
  "auth-jwt": {
@@ -128,7 +128,7 @@ exports.default = (0, config_1.defineConfig)({
128
128
  source: {
129
129
  type: "package",
130
130
  package: "@antelopejs/api",
131
- version: "1.3.3",
131
+ version: "1.3.5",
132
132
  },
133
133
  config: {
134
134
  servers: [{ protocol: "http", host: "127.0.0.1", port: API_PORT }],
@@ -139,14 +139,14 @@ exports.default = (0, config_1.defineConfig)({
139
139
  source: {
140
140
  type: "package",
141
141
  package: "@antelopejs/file-storage-local",
142
- version: "0.1.6",
142
+ version: "0.1.9",
143
143
  },
144
144
  },
145
145
  nodemailer: {
146
146
  source: {
147
147
  type: "package",
148
148
  package: "@antelopejs/nodemailer",
149
- version: "0.0.5",
149
+ version: "0.0.6",
150
150
  },
151
151
  config: {
152
152
  host: SMTP_HOST,
@@ -110,8 +110,8 @@ const detailsRead = useApiData<AssetDetails>(() => (assetId.value ? MEDIA_READS.
110
110
  const details = computed(() => (detailsRead.error.value || detailsRead.placeholder.value ? null : detailsRead.data.value))
111
111
  const asset = computed(() => details.value?.asset)
112
112
  const isEditable = computed(() => Boolean(asset.value && isEditableAsset(asset.value)))
113
- /** The delivery sizes previewed under the crop, which only the browser draws: read once mounted. */
114
- const presetsRead = useApiData<PresetsResponse>(() => (isMounted.value && isEditable.value ? MEDIA_READS.presets : null))
113
+ /** The delivery sizes previewed under the crop, which only the browser draws: left to the browser. */
114
+ const presetsRead = useApiData<PresetsResponse>(() => (isEditable.value ? MEDIA_READS.presets : null), { server: false })
115
115
  const presets = computed<DeliveryPreset[]>(() => presetsRead.data.value?.presets ?? [])
116
116
  const loadState = computed<LoadState>(() => {
117
117
  const error = detailsRead.error.value
@@ -6,7 +6,7 @@
6
6
  "main": "./dms.frontend.ts",
7
7
  "packageManager": "pnpm@10.6.5",
8
8
  "engines": {
9
- "@antelopejs/dms-frontend": ">=0.6.0 <0.7.0"
9
+ "@antelopejs/dms-frontend": ">=0.6.3 <0.7.0"
10
10
  },
11
11
  "scripts": {
12
12
  "dev": "pnpm --dir ../playground frontend:dev",
package/package.json CHANGED
@@ -1,16 +1,31 @@
1
1
  {
2
2
  "name": "@antelopejs/dms-media",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
+ "description": "Media library for the AntelopeJS DMS: uploads, folders with per-folder permissions, image sizes and light editing, with a Finder-style explorer.",
5
+ "keywords": [
6
+ "antelopejs",
7
+ "assets",
8
+ "dms",
9
+ "dms-module",
10
+ "file-explorer",
11
+ "media"
12
+ ],
13
+ "homepage": "https://dms.antelopejs.com/docs/modules/media",
14
+ "bugs": {
15
+ "url": "https://github.com/AntelopeJS/dms-media/issues"
16
+ },
4
17
  "license": "Apache-2.0",
5
18
  "repository": {
6
19
  "type": "git",
7
- "url": "git+https://github.com/AntelopeJS/dms-media.git"
20
+ "url": "git+https://github.com/AntelopeJS/dms-media.git",
21
+ "directory": "packages/dms-media"
8
22
  },
9
23
  "files": [
10
24
  "LICENSE",
11
25
  "dist",
12
26
  "!dist/.tsbuildinfo",
13
27
  "frontend-vue",
28
+ "skills",
14
29
  "src"
15
30
  ],
16
31
  "main": "dist/index.js",
@@ -48,23 +63,23 @@
48
63
  "test:exports": "node --test tests/package-exports.test.mjs"
49
64
  },
50
65
  "dependencies": {
51
- "@antelopejs/interface-api": ">=0.0.14 <1.0.0",
52
- "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
53
- "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
54
- "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
55
- "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
56
- "@antelopejs/interface-dms": ">=0.7.0 <1.0.0",
57
- "@antelopejs/interface-dms-media": ">=0.2.1 <0.3.0",
58
- "@antelopejs/interface-file-storage": ">=0.1.3 <1.0.0",
66
+ "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
67
+ "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
68
+ "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
69
+ "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
70
+ "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
71
+ "@antelopejs/interface-dms": ">=0.7.2 <1.0.0",
72
+ "@antelopejs/interface-dms-media": ">=0.2.2 <0.3.0",
73
+ "@antelopejs/interface-file-storage": ">=0.1.4 <1.0.0",
59
74
  "node-cron": "^4.2.1",
60
75
  "sharp": "^0.34.4",
61
76
  "zod": "~3.24.2"
62
77
  },
63
78
  "devDependencies": {
64
- "@antelopejs/core": ">=1.13.5 <2",
65
- "@antelopejs/dms": ">=0.9.0 <1.0.0",
66
- "@antelopejs/dms-frontend": "0.6.0",
67
- "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
79
+ "@antelopejs/core": ">=1.16.0 <2",
80
+ "@antelopejs/dms": ">=0.9.3 <1.0.0",
81
+ "@antelopejs/dms-frontend": "0.6.3",
82
+ "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
68
83
  "@types/chai": "^4.3.20",
69
84
  "@types/mocha": "^10",
70
85
  "@types/node": "^24.0.0",
@@ -87,6 +102,9 @@
87
102
  "implements": [
88
103
  "@antelopejs/interface-dms-media"
89
104
  ],
90
- "test": "src/test/antelope.test.ts"
105
+ "test": "src/test/antelope.test.ts",
106
+ "skills": [
107
+ "./skills"
108
+ ]
91
109
  }
92
110
  }
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: dms-media
3
+ description: Media library with the @antelopejs/dms-media module of the AntelopeJS DMS. Use when installing or configuring dms-media, adding an image or file field to a DMS form with AssetType, binding a field to a folder and its permissions (permissionsFromPage, permissionMapping, rootAcl), serving images in a given size (presets, /media URLs), or debugging uploads refused by CORS, type, quota or folder rights.
4
+ icon: i-lucide-images
5
+ category: content
6
+ tags: [media, assets, uploads, images, permissions, dms-module]
7
+ ---
8
+
9
+ # dms-media
10
+
11
+ Asset library: folders with per-folder ACL, direct-to-storage uploads, stable `/media` URLs, lazy image sizes, crop/rotate.
12
+ Owner pages under `/modules/media` (overview, files, uploads, file, editor, activity, presets). Members never open them:
13
+ they reach media through `AssetType` fields on project pages. User docs: `docs/` of this package, published at
14
+ https://dms.antelopejs.com/docs/modules/media.
15
+
16
+ ## Setup
17
+
18
+ - Media 0.4 requires `@antelopejs/dms` >=0.9 (interface-dms 0.7, renderer `@antelopejs/dms-frontend` 0.6); 0.3 is the
19
+ DMS 0.8 line.
20
+ - `ajs project modules add @antelopejs/dms-media`, plus an `interface-file-storage` module (`file-storage-local`).
21
+ - Set the storage's `baseUrl` and the module's `publicBaseUrl` to `${@api.API_PUBLIC_BASE_URL}`, and list every
22
+ dashboard origin in the api module's `cors.allowedOrigins`: the browser `PUT`s files straight to the storage.
23
+ - Options: `storage`, `rootAcl` (default empty), `allowedMimetypes` (HTML/XHTML/PHP always refused),
24
+ `storageQuotaBytes`, `publicBaseUrl`, `presets` (`{ id, width?, height?, fit, format, quality }`; keep `thumb`).
25
+
26
+ ## Reference files from a page
27
+
28
+ Put the field in a DMS `Form` block of a backend-declared page; no custom Vue is needed.
29
+
30
+ ```typescript
31
+ import { AssetType } from "@antelopejs/interface-dms-media"; // in the module's dependencies
32
+
33
+ static form = Form({
34
+ fields: [{
35
+ id: "cover",
36
+ label: "$app.articles.cover",
37
+ type: new AssetType({
38
+ mimetypes: ["image/*"], // multiple / max for galleries
39
+ binding: { id: "articles.cover", folderName: "Article covers", permissionsFromPage: ArticlesPage },
40
+ }),
41
+ }],
42
+ });
43
+ ```
44
+
45
+ - The value is an asset id (an array with `multiple`). The `binding` provisions a linked folder under `Content`
46
+ (idempotent on `id`); its rights derive from the page's permission. Explicit `permissionMapping`
47
+ (`{ read: [...], write: [...] }`) wins per right.
48
+ - Only an explicit role grant of the page counts: `memberAccess` / `publicAccess` pages grant no folder right.
49
+ - Rights: `manage` ⇒ `write` ⇒ `read`. Upload needs `write`; folder structure needs `manage`; visibility is owner-only.
50
+
51
+ ## Delivery
52
+
53
+ - `GET /media/<assetId>/<filename>` and `/media/<assetId>/<presetId>/<filename>` (302 to a signed URL; stable
54
+ across edits, renames and visibility changes). Private files need a token.
55
+ - The module declares `/media/**` to the frontend server (`backendProxies`, `auth: "session"`): the same links work on
56
+ the dashboard's origin, a private file opening for a signed-in member. Copied links start with `publicBaseUrl`.
57
+ - Authenticated: `GET /api/media/assets/:id/read-url?preset=`.
58
+
59
+ ## Gotchas
60
+
61
+ - Upload refusals answer `{ reason }`: `type_not_allowed` / `field_type` (415), `quota` (413), `invalid_image` (422).
62
+ - Linked folders cannot be renamed, moved, deleted, re-ACLed or hold subfolders (403 `bound_parent`).
63
+ - Names are unique per folder, case aside (409 `name_taken`).
64
+ - Editing an image changes it everywhere it is used; there is no per-usage crop and no usage tracking yet.
@@ -109,7 +109,7 @@ export default defineConfig({
109
109
  source: {
110
110
  type: "package",
111
111
  package: "@antelopejs/dms",
112
- version: ">=0.9.0 <1.0.0",
112
+ version: ">=0.9.3 <1.0.0",
113
113
  },
114
114
  config: {
115
115
  auth: {
@@ -121,7 +121,7 @@ export default defineConfig({
121
121
  source: {
122
122
  type: "package",
123
123
  package: "@antelopejs/mongodb",
124
- version: "1.4.2",
124
+ version: "1.4.3",
125
125
  },
126
126
  },
127
127
  "auth-jwt": {
@@ -138,7 +138,7 @@ export default defineConfig({
138
138
  source: {
139
139
  type: "package",
140
140
  package: "@antelopejs/api",
141
- version: "1.3.3",
141
+ version: "1.3.5",
142
142
  },
143
143
  config: {
144
144
  servers: [{ protocol: "http", host: "127.0.0.1", port: API_PORT }],
@@ -149,14 +149,14 @@ export default defineConfig({
149
149
  source: {
150
150
  type: "package",
151
151
  package: "@antelopejs/file-storage-local",
152
- version: "0.1.6",
152
+ version: "0.1.9",
153
153
  },
154
154
  },
155
155
  nodemailer: {
156
156
  source: {
157
157
  type: "package",
158
158
  package: "@antelopejs/nodemailer",
159
- version: "0.0.5",
159
+ version: "0.0.6",
160
160
  },
161
161
  config: {
162
162
  host: SMTP_HOST,