@antelopejs/dms-media 0.3.1 → 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.
Files changed (54) hide show
  1. package/README.md +57 -180
  2. package/dist/db/models/mediaAssets.model.d.ts +1 -0
  3. package/dist/db/models/mediaEvents.model.d.ts +1 -0
  4. package/dist/db/models/mediaFavorites.model.d.ts +1 -0
  5. package/dist/db/models/mediaFolders.model.d.ts +1 -0
  6. package/dist/db/models/mediaUploads.model.d.ts +1 -0
  7. package/dist/index.d.ts +3 -0
  8. package/dist/index.js +8 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/test/antelope.test.js +5 -5
  11. package/dist/test/helpers/pages.js +3 -2
  12. package/dist/test/helpers/pages.js.map +1 -1
  13. package/dist/test/integration/frontend-module.test.d.ts +1 -0
  14. package/dist/test/integration/frontend-module.test.js +13 -0
  15. package/dist/test/integration/frontend-module.test.js.map +1 -0
  16. package/frontend-vue/app/components/FileProperties.vue +9 -3
  17. package/frontend-vue/app/components/FirstRun.vue +1 -1
  18. package/frontend-vue/app/components/ImageEditor.vue +43 -26
  19. package/frontend-vue/app/components/PresetCards.vue +3 -11
  20. package/frontend-vue/app/components/RecentFiles.vue +6 -14
  21. package/frontend-vue/app/components/UploadQueue.vue +1 -1
  22. package/frontend-vue/app/components/UploadStrip.vue +1 -1
  23. package/frontend-vue/app/components/dialogs/DestinationDialog.vue +1 -2
  24. package/frontend-vue/app/components/explorer/ExplorerInspector.vue +17 -16
  25. package/frontend-vue/app/components/explorer/ExplorerShell.vue +11 -3
  26. package/frontend-vue/app/components/explorer/ExplorerToolbar.vue +2 -1
  27. package/frontend-vue/app/components/field/AssetValue.vue +12 -13
  28. package/frontend-vue/app/components/file/FileViewer.vue +1 -14
  29. package/frontend-vue/app/composables/library/useLibraryListing.ts +180 -79
  30. package/frontend-vue/app/composables/library/useLibraryTree.ts +31 -15
  31. package/frontend-vue/app/composables/library/useMediaLibrary.ts +17 -7
  32. package/frontend-vue/app/composables/uploadLimits.ts +25 -0
  33. package/frontend-vue/app/composables/useAssetContent.ts +20 -0
  34. package/frontend-vue/app/composables/useCurrentFile.ts +10 -8
  35. package/frontend-vue/app/composables/useFieldFolders.ts +19 -18
  36. package/frontend-vue/app/composables/useFileDetails.ts +117 -90
  37. package/frontend-vue/app/composables/useMediaApi.ts +18 -24
  38. package/frontend-vue/package.json +2 -1
  39. package/frontend-vue/pnpm-lock.yaml +17 -2
  40. package/frontend-vue/tests/engines.test.ts +20 -0
  41. package/frontend-vue/tests/fixtures/inertia.ts +8 -0
  42. package/frontend-vue/tests/fixtures/serverRender.ts +200 -0
  43. package/frontend-vue/tests/fixtures/unhead.ts +3 -0
  44. package/frontend-vue/tests/fixtures/vueI18n.ts +4 -0
  45. package/frontend-vue/tests/libraryListing.test.ts +120 -0
  46. package/frontend-vue/tests/serverRender.test.ts +215 -0
  47. package/frontend-vue/vitest.config.ts +21 -0
  48. package/package.json +40 -16
  49. package/skills/dms-media/SKILL.md +64 -0
  50. package/src/index.ts +19 -2
  51. package/src/test/antelope.test.ts +5 -5
  52. package/src/test/helpers/pages.ts +3 -2
  53. package/src/test/integration/frontend-module.test.ts +13 -0
  54. package/frontend-vue/app/composables/useSharedTree.ts +0 -73
@@ -0,0 +1,120 @@
1
+ import { describe, expect, it } from 'vitest'
2
+ import { inBrowserApp, type BackendRead } from './fixtures/serverRender'
3
+ import { useLibraryListing } from '../app/composables/library/useLibraryListing'
4
+ import type { MediaAsset } from '../app/types/media'
5
+
6
+ // The explorer's listing is one paged read keyed by the location and the
7
+ // filters: "load more" appends a page, a revalidation reads every loaded page
8
+ // again with the sizes they had, and the local patches keep the next page's
9
+ // offset in step with the server.
10
+
11
+ const FOLDER_FILES = 650
12
+ const FOLDER_URL = '/api/media/folders/catalog/assets'
13
+
14
+ const file = (index: number): MediaAsset => ({
15
+ id: `f${index}`,
16
+ folderId: 'catalog',
17
+ name: `file-${String(index).padStart(4, '0')}.pdf`,
18
+ mimetype: 'application/pdf',
19
+ size: 1000,
20
+ alt: '',
21
+ visibility: 'inherit',
22
+ effectiveVisibility: 'private',
23
+ url: `/media/f${index}/file.pdf`,
24
+ hasOriginal: false,
25
+ typeGroup: 'document',
26
+ starred: false,
27
+ createdAt: '2026-10-01T10:00:00.000Z',
28
+ updatedAt: '2026-10-01T10:00:00.000Z',
29
+ })
30
+
31
+ function folderBackend(files: MediaAsset[]) {
32
+ return ({ url, query }: BackendRead): unknown => {
33
+ if (url !== FOLDER_URL) return {}
34
+ const offset = Number(query.offset)
35
+ const limit = Number(query.limit)
36
+ const sorted = query.direction === 'desc' ? [...files].reverse() : files
37
+ return { assets: sorted.slice(offset, offset + limit), total: files.length, facets: {} }
38
+ }
39
+ }
40
+
41
+ function openListing(files = Array.from({ length: FOLDER_FILES }, (_, index) => file(index))) {
42
+ const app = inBrowserApp(() => useLibraryListing(), folderBackend(files))
43
+ const folderReads = () => app.reads().filter((read) => read.includes(FOLDER_URL))
44
+ return { listing: app.result, folderReads, files }
45
+ }
46
+
47
+ describe('the explorer listing', () => {
48
+ it('reads nothing at the root', () => {
49
+ const { listing, folderReads } = openListing()
50
+ expect(listing.assets.value).toEqual([])
51
+ expect(folderReads()).toEqual([])
52
+ })
53
+
54
+ it('reads a folder page by page', async () => {
55
+ const { listing, folderReads } = openListing()
56
+ await listing.setLocation({ kind: 'folder', folderId: 'catalog' })
57
+ expect(listing.assets.value).toHaveLength(120)
58
+ expect(listing.total.value).toBe(FOLDER_FILES)
59
+ expect(listing.hasMore.value).toBe(true)
60
+
61
+ await listing.load(true)
62
+ expect(listing.assets.value).toHaveLength(240)
63
+ expect(listing.assets.value[120]?.id).toBe('f120')
64
+ expect(folderReads()).toEqual([
65
+ `GET ${FOLDER_URL}?offset=0&limit=120&sort=name&direction=asc&visibility=any&modified=any&orientation=any`,
66
+ `GET ${FOLDER_URL}?offset=120&limit=120&sort=name&direction=asc&visibility=any&modified=any&orientation=any`,
67
+ ])
68
+ })
69
+
70
+ it('reads the next page after the files left once some are removed', async () => {
71
+ const { listing, folderReads, files } = openListing()
72
+ await listing.setLocation({ kind: 'folder', folderId: 'catalog' })
73
+ listing.removeAssets(['f0', 'f1'])
74
+ files.splice(0, 2)
75
+ expect(listing.total.value).toBe(FOLDER_FILES - 2)
76
+
77
+ await listing.load(true)
78
+ expect(folderReads().at(-1)).toContain('offset=118&limit=120')
79
+ expect(listing.assets.value.map((asset) => asset.id)).toEqual(files.slice(0, 238).map((asset) => asset.id))
80
+ })
81
+
82
+ it('loads every file in the largest pages, and reads them again with the same sizes', async () => {
83
+ const { listing, folderReads } = openListing()
84
+ await listing.setLocation({ kind: 'folder', folderId: 'catalog' })
85
+ await listing.loadAll()
86
+ expect(listing.assets.value).toHaveLength(FOLDER_FILES)
87
+ expect(listing.hasMore.value).toBe(false)
88
+ const loaded = folderReads().map((read) => read.match(/offset=\d+&limit=\d+/)?.[0])
89
+ expect(loaded).toEqual(['offset=0&limit=120', 'offset=120&limit=500', 'offset=620&limit=500'])
90
+
91
+ await listing.refresh()
92
+ expect(folderReads().slice(loaded.length).map((read) => read.match(/offset=\d+&limit=\d+/)?.[0])).toEqual(loaded)
93
+ expect(listing.assets.value).toHaveLength(FOLDER_FILES)
94
+ })
95
+
96
+ it('starts again from the first page when the filters change, and shows the pages of a previous key at once', async () => {
97
+ const { listing, folderReads } = openListing()
98
+ await listing.setLocation({ kind: 'folder', folderId: 'catalog' })
99
+ await listing.load(true)
100
+ await listing.setFilters({ direction: 'desc' })
101
+ expect(listing.assets.value).toHaveLength(120)
102
+ expect(listing.assets.value[0]?.id).toBe(`f${FOLDER_FILES - 1}`)
103
+ expect(folderReads().at(-1)).toContain('offset=0&limit=120&sort=name&direction=desc')
104
+
105
+ const back = listing.setFilters({ direction: 'asc' })
106
+ await nextTick()
107
+ expect(listing.assets.value).toHaveLength(240)
108
+ await back
109
+ })
110
+
111
+ it('places a new file where the sort puts it and counts one beyond the loaded pages', async () => {
112
+ const { listing } = openListing()
113
+ await listing.setLocation({ kind: 'folder', folderId: 'catalog' })
114
+ listing.insertAsset({ ...file(9000), name: 'file-0000a.pdf' })
115
+ expect(listing.assets.value[1]?.id).toBe('f9000')
116
+ listing.insertAsset({ ...file(9001), name: 'zzz.pdf' })
117
+ expect(listing.assets.value).toHaveLength(121)
118
+ expect(listing.total.value).toBe(FOLDER_FILES + 2)
119
+ })
120
+ })
@@ -0,0 +1,215 @@
1
+ import { defineComponent, h } from 'vue'
2
+ import { describe, expect, it } from 'vitest'
3
+ import { serverRender, type BackendRead } from './fixtures/serverRender'
4
+ import AssetValue from '../app/components/field/AssetValue.vue'
5
+ import Explorer from '../app/components/Explorer.vue'
6
+ import FileHeader from '../app/components/FileHeader.vue'
7
+ import FilePreview from '../app/components/FilePreview.vue'
8
+ import FileProperties from '../app/components/FileProperties.vue'
9
+ import ImageEditor from '../app/components/ImageEditor.vue'
10
+ import PresetCards from '../app/components/PresetCards.vue'
11
+ import RecentFiles from '../app/components/RecentFiles.vue'
12
+ import { useFieldFolders } from '../app/composables/useFieldFolders'
13
+ import type { MediaAsset, MediaFolder } from '../app/types/media'
14
+
15
+ // What a server render of each block reads, and that it hands every read to
16
+ // the browser: a read the page does not hand over is made again by the
17
+ // browser, after a server request for nothing.
18
+
19
+ const RIGHTS = { read: true, write: true, manage: true }
20
+
21
+ const folder = (id: string, name: string): MediaFolder => ({
22
+ id,
23
+ name,
24
+ parentId: null,
25
+ shell: false,
26
+ bound: false,
27
+ binding: null,
28
+ link: null,
29
+ accepts: null,
30
+ visibility: 'private',
31
+ hasOwnAcl: false,
32
+ createdAt: '2026-10-01T10:00:00.000Z',
33
+ updatedAt: '2026-10-01T10:00:00.000Z',
34
+ rights: RIGHTS,
35
+ fileCount: 3,
36
+ size: 3000,
37
+ starred: false,
38
+ })
39
+
40
+ const file = (id: string, name: string, mimetype = 'image/png'): MediaAsset => ({
41
+ id,
42
+ folderId: 'catalog',
43
+ name,
44
+ mimetype,
45
+ size: 1000,
46
+ width: 1200,
47
+ height: 800,
48
+ alt: `${name} alt`,
49
+ visibility: 'inherit',
50
+ effectiveVisibility: 'private',
51
+ url: `/media/${id}/${name}`,
52
+ hasOriginal: false,
53
+ typeGroup: mimetype.startsWith('image/') ? 'image' : 'document',
54
+ starred: false,
55
+ createdAt: '2026-10-01T10:00:00.000Z',
56
+ updatedAt: '2026-10-01T10:00:00.000Z',
57
+ })
58
+
59
+ const FILES = [file('a1', 'harbour.png'), file('a2', 'lighthouse.png'), file('a3', 'dunes.png')]
60
+
61
+ function backend({ url }: BackendRead): unknown {
62
+ const details = url.match(/^\/api\/media\/assets\/([^/]+)\/details$/)
63
+ if (details) {
64
+ const found = FILES.find((entry) => entry.id === details[1])
65
+ if (!found) throw Object.assign(new Error('Not Found'), { statusCode: 404 })
66
+ return { asset: found, folder: folder('catalog', 'Catalog'), path: [], uploadedBy: null }
67
+ }
68
+ const one = url.match(/^\/api\/media\/assets\/([^/]+)$/)
69
+ if (one) return { asset: FILES.find((entry) => entry.id === one[1]) }
70
+ if (/\/read-url$/.test(url)) return { url: `https://storage.test${url}`, expiresAt: 0 }
71
+ switch (url) {
72
+ case '/api/media/tree':
73
+ return {
74
+ folders: [folder('catalog', 'Catalog')],
75
+ root: { write: true, manage: true, fileCount: 3, size: 3000 },
76
+ views: { starred: 0, missingAlt: 0 },
77
+ isOwner: true,
78
+ maxUploadBytes: 1000,
79
+ allowedMimetypes: [],
80
+ quotaBytes: null,
81
+ }
82
+ case '/api/media/stats/recent':
83
+ return { assets: FILES }
84
+ case '/api/media/presets':
85
+ return {
86
+ presets: [{ id: 'thumb', width: 300, height: 300, fit: 'cover', cacheKey: 'thumb.1', rendered: 1, urlPattern: '', exampleUrl: null }],
87
+ cache: { schedule: '', lastSweepAt: null, lastSweepRemoved: null, publicTtlSeconds: 0, privateTtlSeconds: 0 },
88
+ isDefault: true,
89
+ example: null,
90
+ }
91
+ case '/api/media/folders/catalog/assets':
92
+ return { assets: FILES, total: FILES.length, facets: {} }
93
+ case '/api/media/bindings/demo.cover/folder':
94
+ return { folder: { ...folder('covers', 'Demo covers'), bound: true }, maxUploadBytes: 1000, allowedMimetypes: [] }
95
+ default:
96
+ return {}
97
+ }
98
+ }
99
+
100
+ const render = (component: Parameters<typeof serverRender>[0], props: Record<string, unknown> = {}, url = '/') =>
101
+ serverRender(component, props, { url, respond: backend })
102
+
103
+ /** The file page's blocks, as the page lays them out. */
104
+ const FilePage = defineComponent({
105
+ setup: () => () => h('div', [h(FileHeader), h(FilePreview), h(FileProperties)]),
106
+ })
107
+
108
+ describe('server render: the blocks read with the page and hand it over', () => {
109
+ it('recent files: the files and the folder tree', async () => {
110
+ const page = await render(RecentFiles)
111
+ expect(page.reads).toEqual(['GET /api/media/stats/recent', 'GET /api/media/tree'])
112
+ expect(page.handed).toEqual(expect.arrayContaining(page.reads))
113
+ expect(page.html).toContain('lighthouse.png')
114
+ expect(page.html).not.toContain('animate-pulse')
115
+ })
116
+
117
+ it('image sizes: the presets', async () => {
118
+ const page = await render(PresetCards)
119
+ expect(page.reads).toEqual(['GET /api/media/presets'])
120
+ expect(page.handed).toEqual(expect.arrayContaining(page.reads))
121
+ expect(page.html).toContain('thumb')
122
+ })
123
+
124
+ it('file page: one read of the file and its neighbours for the three blocks, and the image read URL', async () => {
125
+ const page = await render(FilePage, {}, '/modules/media/file?asset=a2')
126
+ expect(page.reads.sort()).toEqual(
127
+ [
128
+ 'GET /api/media/tree',
129
+ 'GET /api/media/assets/a2/details',
130
+ 'GET /api/media/folders/catalog/assets?sort=name&offset=0&limit=500',
131
+ 'GET /api/media/assets/a2/read-url?preset=preview',
132
+ ].sort(),
133
+ )
134
+ expect(page.handed).toEqual(
135
+ expect.arrayContaining([
136
+ 'GET /api/media/tree',
137
+ 'dms-media:file:a2:[null,null,null]',
138
+ 'dms-media:content:a2:2026-10-01T10:00:00.000Z',
139
+ ]),
140
+ )
141
+ // The header's name and position, the viewer's image, the name field.
142
+ expect(page.html).toContain('lighthouse.png')
143
+ expect(page.html).toContain('dms_media.lightbox.position 2 3')
144
+ expect(page.html).toContain('https://storage.test/api/media/assets/a2/read-url')
145
+ expect(page.html).toContain('value="lighthouse"')
146
+ })
147
+
148
+ it('file page: a text file is read by the browser alone', async () => {
149
+ FILES.push(file('t1', 'notes.txt', 'text/plain'))
150
+ try {
151
+ const page = await render(FilePage, {}, '/modules/media/file?asset=t1')
152
+ expect(page.reads).not.toContain(expect.stringContaining('read-url'))
153
+ expect(page.html).toContain('notes.txt')
154
+ } finally {
155
+ FILES.pop()
156
+ }
157
+ })
158
+
159
+ it('file page: an unknown file is said so, and the failure handed over', async () => {
160
+ const page = await render(FilePage, {}, '/modules/media/file?asset=gone')
161
+ expect(page.reads).toContain('GET /api/media/assets/gone/details')
162
+ expect(page.payload.errors).toHaveProperty(['dms-media:file:gone:[null,null,null]'])
163
+ expect(page.html).toContain('dms_media.file.not_found')
164
+ })
165
+
166
+ it('library: a link to a folder reads its files with the page', async () => {
167
+ const page = await render(Explorer, {}, '/modules/media/files?folder=catalog&sort=name&direction=desc')
168
+ expect(page.reads).toEqual([
169
+ 'GET /api/media/tree',
170
+ 'GET /api/media/folders/catalog/assets?offset=0&limit=120&sort=name&direction=desc&visibility=any&modified=any&orientation=any',
171
+ ])
172
+ expect(page.handed).toEqual(expect.arrayContaining(['GET /api/media/tree']))
173
+ expect(page.handed.some((key) => key.startsWith('dms-media:listing:'))).toBe(true)
174
+ expect(page.html).toContain('aria-current="location">Catalog')
175
+ expect(page.html).toContain('dms_media.status.items 3')
176
+ })
177
+
178
+ it('library and image editor: the key hints are the platform labels the browser hydrates with', async () => {
179
+ const library = await render(Explorer, {}, '/modules/media/files')
180
+ const editor = await render(ImageEditor, {}, '/modules/media/editor?asset=a1')
181
+ for (const page of [library, editor]) {
182
+ expect(page.html).not.toContain('data-stub="UKbd" value="meta"')
183
+ expect(page.html).toContain('data-stub="UKbd" value="Ctrl"')
184
+ }
185
+ })
186
+
187
+ it('image editor: the details, not the image the browser edits', async () => {
188
+ const page = await render(ImageEditor, {}, '/modules/media/editor?asset=a1')
189
+ expect(page.reads).toEqual(['GET /api/media/assets/a1/details'])
190
+ expect(page.handed).toEqual(expect.arrayContaining(page.reads))
191
+ expect(page.html).toContain('dms_media.editor.heading harbour.png')
192
+ })
193
+
194
+ it('asset cell: the files it names', async () => {
195
+ const page = await render(AssetValue, { value: ['a1', 'a3', 'a2'] })
196
+ expect(page.reads).toEqual(['GET /api/media/assets/a1', 'GET /api/media/assets/a3'])
197
+ expect(page.handed).toEqual(['dms-media:asset-names:a1,a3'])
198
+ expect(page.html).toContain('harbour.png')
199
+ expect(page.html).toContain('dunes.png')
200
+ expect(page.html).toContain('dms_media.field_widget.more 1')
201
+ })
202
+
203
+ it('bound asset field: its folder', async () => {
204
+ const Field = defineComponent({
205
+ setup() {
206
+ const { boundFolder } = useFieldFolders('demo.cover')
207
+ return () => h('p', boundFolder.value?.name ?? 'no folder')
208
+ },
209
+ })
210
+ const page = await render(Field)
211
+ expect(page.reads).toEqual(['GET /api/media/bindings/demo.cover/folder'])
212
+ expect(page.handed).toEqual(page.reads)
213
+ expect(page.html).toContain('Demo covers')
214
+ })
215
+ })
@@ -1,5 +1,26 @@
1
+ import { resolve } from 'node:path'
2
+ import vue from '@vitejs/plugin-vue'
1
3
  import { defineConfig } from 'vitest/config'
2
4
 
5
+ // The renderer and the DMS core layer the server-render tests run on: the
6
+ // ones the module installs (`@antelopejs/dms-frontend`, `@antelopejs/dms`),
7
+ // as `pnpm test:frontend` checks the module against them.
8
+ const root = resolve(__dirname, '..', 'node_modules', '@antelopejs')
9
+
3
10
  export default defineConfig({
11
+ plugins: [vue()],
12
+ resolve: {
13
+ alias: {
14
+ '#dms/frontend-module': resolve(root, 'dms-frontend/templates/vue/frontend-module.ts'),
15
+ '#dms-core': resolve(root, 'dms/frontend-vue/layers/dms-core'),
16
+ '#dms-ui': resolve(root, 'dms/frontend-vue/layers/dms-ui'),
17
+ // One Vue for the renderer and the components.
18
+ vue: resolve(__dirname, 'node_modules/vue'),
19
+ // What the renderer reads of Inertia, vue-i18n and unhead in the browser only.
20
+ '@inertiajs/vue3': resolve(__dirname, 'tests/fixtures/inertia.ts'),
21
+ 'vue-i18n': resolve(__dirname, 'tests/fixtures/vueI18n.ts'),
22
+ '@unhead/vue': resolve(__dirname, 'tests/fixtures/unhead.ts'),
23
+ },
24
+ },
4
25
  test: { environment: 'node', include: ['tests/**/*.test.ts'] },
5
26
  })
package/package.json CHANGED
@@ -1,20 +1,40 @@
1
1
  {
2
2
  "name": "@antelopejs/dms-media",
3
- "version": "0.3.1",
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",
32
+ "types": "dist/index.d.ts",
17
33
  "exports": {
34
+ ".": {
35
+ "types": "./dist/index.d.ts",
36
+ "default": "./dist/index.js"
37
+ },
18
38
  "./package.json": "./package.json"
19
39
  },
20
40
  "publishConfig": {
@@ -39,26 +59,27 @@
39
59
  "release": "pnpm --filter @antelopejs/interface-dms-media build && pnpm --dir frontend-vue install --frozen-lockfile && release-it",
40
60
  "prepack": "pnpm run build",
41
61
  "knip": "knip --dependencies",
42
- "knip:all": "knip"
62
+ "knip:all": "knip",
63
+ "test:exports": "node --test tests/package-exports.test.mjs"
43
64
  },
44
65
  "dependencies": {
45
- "@antelopejs/interface-api": ">=0.0.14 <1.0.0",
46
- "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
47
- "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
48
- "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
49
- "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
50
- "@antelopejs/interface-dms": ">=0.6.0 <1.0.0",
51
- "@antelopejs/interface-dms-media": ">=0.2.1 <0.3.0",
52
- "@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",
53
74
  "node-cron": "^4.2.1",
54
75
  "sharp": "^0.34.4",
55
76
  "zod": "~3.24.2"
56
77
  },
57
78
  "devDependencies": {
58
- "@antelopejs/core": ">=1.13.5 <2",
59
- "@antelopejs/dms": ">=0.8.0 <0.9.0",
60
- "@antelopejs/dms-frontend": "0.5.6",
61
- "@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",
62
83
  "@types/chai": "^4.3.20",
63
84
  "@types/mocha": "^10",
64
85
  "@types/node": "^24.0.0",
@@ -81,6 +102,9 @@
81
102
  "implements": [
82
103
  "@antelopejs/interface-dms-media"
83
104
  ],
84
- "test": "src/test/antelope.test.ts"
105
+ "test": "src/test/antelope.test.ts",
106
+ "skills": [
107
+ "./skills"
108
+ ]
85
109
  }
86
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.
package/src/index.ts CHANGED
@@ -1,6 +1,9 @@
1
1
  import path from "node:path";
2
2
  import { ImplementInterface } from "@antelopejs/interface-core";
3
- import { AddFrontendModule } from "@antelopejs/interface-dms/page";
3
+ import {
4
+ AddFrontendModule,
5
+ type FrontendBackendProxy,
6
+ } from "@antelopejs/interface-dms/page";
4
7
  import { Logging } from "@antelopejs/interface-core/logging";
5
8
  import "./db";
6
9
  import type { ScheduledTask } from "node-cron";
@@ -23,6 +26,19 @@ export * from "./types";
23
26
 
24
27
  let cronTasks: ScheduledTask[] = [];
25
28
 
29
+ /** The frontend module the dashboard loads: its blocks, viewers and fields. */
30
+ export const MEDIA_FRONTEND_MODULE = "@antelopejs/dms-media-frontend-vue";
31
+
32
+ /**
33
+ * The file links a dashboard page shows (`/media/<id>/<name>`), which the
34
+ * backend serves: proxied by the frontend server with the member's session,
35
+ * so that a private file opens for a member signed in, as on the API origin.
36
+ */
37
+ export const MEDIA_DELIVERY_PROXY: FrontendBackendProxy = {
38
+ path: "/media/**",
39
+ auth: "session",
40
+ };
41
+
26
42
  export async function construct(config: DmsMediaConfig = {}): Promise<void> {
27
43
  configureMediaModule(config);
28
44
  ImplementInterface(
@@ -32,11 +48,12 @@ export async function construct(config: DmsMediaConfig = {}): Promise<void> {
32
48
  const sourcePath = path.join(__dirname, "../frontend-vue");
33
49
 
34
50
  await AddFrontendModule({
35
- name: "@antelopejs/dms-media-frontend-vue",
51
+ name: MEDIA_FRONTEND_MODULE,
36
52
  sourcePath,
37
53
  renderer: { name: "vue", version: "3" },
38
54
  configKey: "dmsMedia",
39
55
  priority: 0,
56
+ backendProxies: [MEDIA_DELIVERY_PROXY],
40
57
  });
41
58
  }
42
59
 
@@ -109,7 +109,7 @@ export default defineConfig({
109
109
  source: {
110
110
  type: "package",
111
111
  package: "@antelopejs/dms",
112
- version: ">=0.8.0 <0.9.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,
@@ -1,7 +1,8 @@
1
+ import { pageRoutePath } from "@antelopejs/interface-dms/page";
1
2
  import type { AxiosInstance } from "axios";
2
3
 
3
4
  const HTTP_OK = 200;
4
- const PAGE_LAYOUT_SUFFIX = "/pagelayout";
5
+ const PAGE_LAYOUT_ROUTE = "/pagelayout";
5
6
  const OMIT_SHARED_PAGE = "false";
6
7
 
7
8
  /** What a caller gets from each surface that serves a DMS page. */
@@ -25,7 +26,7 @@ export async function readPageAccess(
25
26
  slug: string,
26
27
  ): Promise<PageAccess> {
27
28
  const [ownRoute, page, layout] = await Promise.all([
28
- client.get(`${slug}${PAGE_LAYOUT_SUFFIX}`),
29
+ client.get(pageRoutePath(slug, PAGE_LAYOUT_ROUTE)),
29
30
  client.get("/dms/page", {
30
31
  params: { path: slug, shared: OMIT_SHARED_PAGE },
31
32
  }),
@@ -0,0 +1,13 @@
1
+ import { GetFrontendModules } from "@antelopejs/interface-dms/page";
2
+ import { expect } from "chai";
3
+ import { MEDIA_DELIVERY_PROXY, MEDIA_FRONTEND_MODULE } from "../../index";
4
+
5
+ describe("frontend module", () => {
6
+ it("declares the file links as a backend prefix the frontend server proxies with the session", async () => {
7
+ const modules = await GetFrontendModules();
8
+ const media = modules.find(
9
+ (module) => module.name === MEDIA_FRONTEND_MODULE,
10
+ );
11
+ expect(media?.backendProxies).to.deep.equal([MEDIA_DELIVERY_PROXY]);
12
+ });
13
+ });