@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 +57 -184
- package/dist/db/models/mediaAssets.model.d.ts +1 -0
- package/dist/db/models/mediaEvents.model.d.ts +1 -0
- package/dist/db/models/mediaFavorites.model.d.ts +1 -0
- package/dist/db/models/mediaFolders.model.d.ts +1 -0
- package/dist/db/models/mediaUploads.model.d.ts +1 -0
- package/dist/test/antelope.test.js +5 -5
- package/frontend-vue/app/components/ImageEditor.vue +2 -2
- package/frontend-vue/package.json +1 -1
- package/package.json +33 -15
- package/skills/dms-media/SKILL.md +64 -0
- package/src/test/antelope.test.ts +5 -5
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
10
|
+
A media library for the AntelopeJS DMS: uploads, folders, image sizes and light editing.
|
|
37
11
|
|
|
38
|
-
|
|
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
|
-
|
|
14
|
+

|
|
43
15
|
|
|
44
|
-
##
|
|
16
|
+
## What it does
|
|
45
17
|
|
|
46
|
-
|
|
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
|
-
|
|
24
|
+
## Install
|
|
49
25
|
|
|
50
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
{
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
-
|
|
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
|
-
|
|
136
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
72
|
+
On DMS 0.8, use `@antelopejs/dms-media` 0.3.
|
|
200
73
|
|
|
201
|
-
|
|
74
|
+
## Documentation
|
|
202
75
|
|
|
203
|
-
|
|
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
|
|
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
|
-
|
|
85
|
+
## Contributing
|
|
208
86
|
|
|
209
|
-
|
|
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
|
-
##
|
|
89
|
+
## License
|
|
212
90
|
|
|
213
|
-
-
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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:
|
|
114
|
-
const presetsRead = useApiData<PresetsResponse>(() => (
|
|
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
|
package/package.json
CHANGED
|
@@ -1,16 +1,31 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/dms-media",
|
|
3
|
-
"version": "0.4.
|
|
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.
|
|
52
|
-
"@antelopejs/interface-api-util": ">=0.1.
|
|
53
|
-
"@antelopejs/interface-core": ">=0.
|
|
54
|
-
"@antelopejs/interface-database": ">=0.1.
|
|
55
|
-
"@antelopejs/interface-database-decorators": ">=0.1.
|
|
56
|
-
"@antelopejs/interface-dms": ">=0.7.
|
|
57
|
-
"@antelopejs/interface-dms-media": ">=0.2.
|
|
58
|
-
"@antelopejs/interface-file-storage": ">=0.1.
|
|
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.
|
|
65
|
-
"@antelopejs/dms": ">=0.9.
|
|
66
|
-
"@antelopejs/dms-frontend": "0.6.
|
|
67
|
-
"@antelopejs/tooling-configs": ">=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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
159
|
+
version: "0.0.6",
|
|
160
160
|
},
|
|
161
161
|
config: {
|
|
162
162
|
host: SMTP_HOST,
|