@adonis-agora/media-dashboard 7.0.0 → 8.0.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/CHANGELOG.md +16 -0
- package/dist/provider/media_dashboard_provider.d.ts +15 -4
- package/dist/provider/media_dashboard_provider.d.ts.map +1 -1
- package/dist/provider/media_dashboard_provider.js +19 -9
- package/dist/provider/media_dashboard_provider.js.map +1 -1
- package/dist/spa/assets/index-Bo658_9z.js +83 -0
- package/dist/spa/assets/{index-Dvw2uJpF.js.map → index-Bo658_9z.js.map} +1 -1
- package/dist/spa/index.html +1 -1
- package/package.json +9 -5
- package/skills/media-dashboard-console/SKILL.md +277 -0
- package/dist/spa/assets/index-Dvw2uJpF.js +0 -83
package/dist/spa/index.html
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
rel="stylesheet"
|
|
12
12
|
/>
|
|
13
13
|
<title>Media · Agora</title>
|
|
14
|
-
<script type="module" crossorigin src="/__MEDIA_DASHBOARD__/assets/index-
|
|
14
|
+
<script type="module" crossorigin src="/__MEDIA_DASHBOARD__/assets/index-Bo658_9z.js"></script>
|
|
15
15
|
<link rel="stylesheet" crossorigin href="/__MEDIA_DASHBOARD__/assets/index--0MZJr6W.css">
|
|
16
16
|
</head>
|
|
17
17
|
<body>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adonis-agora/media-dashboard",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "8.0.1",
|
|
4
4
|
"description": "Media-management dashboard for @adonis-agora/media — browse buckets, watch resumable uploads in progress, upload, and copy/move/delete objects across buckets. A React SPA served by a thin AdonisJS provider, themed to Agora design tokens. Part of the Agora ecosystem.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -32,14 +32,16 @@
|
|
|
32
32
|
"files": [
|
|
33
33
|
"dist/",
|
|
34
34
|
"README.md",
|
|
35
|
-
"CHANGELOG.md"
|
|
35
|
+
"CHANGELOG.md",
|
|
36
|
+
"skills"
|
|
36
37
|
],
|
|
37
38
|
"sideEffects": false,
|
|
38
39
|
"peerDependencies": {
|
|
39
|
-
"@adonis-agora/media": "
|
|
40
|
+
"@adonis-agora/media": ">=0.11.0 <1.0.0",
|
|
40
41
|
"@adonisjs/core": "^7.3.0"
|
|
41
42
|
},
|
|
42
43
|
"devDependencies": {
|
|
44
|
+
"@adonis-agora/media": "npm:@adonis-agora/media@0.11.0",
|
|
43
45
|
"@adonisjs/core": "7.4.0",
|
|
44
46
|
"@base-ui/react": "1.0.0",
|
|
45
47
|
"@tanstack/react-query": "5.101.4",
|
|
@@ -60,7 +62,8 @@
|
|
|
60
62
|
"typescript": "^5.4.0",
|
|
61
63
|
"vite": "^6.0.0",
|
|
62
64
|
"vitest": "3.2.7",
|
|
63
|
-
"@
|
|
65
|
+
"@tanstack/intent": "^0.3.2",
|
|
66
|
+
"@adonis-agora/media-react": "0.5.1"
|
|
64
67
|
},
|
|
65
68
|
"engines": {
|
|
66
69
|
"node": ">=20.6.0"
|
|
@@ -76,7 +79,8 @@
|
|
|
76
79
|
"buckets",
|
|
77
80
|
"upload",
|
|
78
81
|
"resumable",
|
|
79
|
-
"agora"
|
|
82
|
+
"agora",
|
|
83
|
+
"tanstack-intent"
|
|
80
84
|
],
|
|
81
85
|
"scripts": {
|
|
82
86
|
"build": "vite build && tsc -p tsconfig.server.json",
|
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: media-dashboard-console
|
|
3
|
+
description: >-
|
|
4
|
+
The media management console for @adonis-agora/media — config/media_dashboard.ts via
|
|
5
|
+
@adonis-agora/media/dashboard defineConfig (basePath, apiBasePath, actions gate, disks,
|
|
6
|
+
middleware, enabled), the embedded dashboard_provider vs the standalone
|
|
7
|
+
@adonis-agora/media-dashboard delegate provider, built-in session auth (Mode A
|
|
8
|
+
auth.session minting from app auth, Mode B auth.login credentials screen, revalidate,
|
|
9
|
+
secret/ttl, signSessionCookie/verifySessionCookie/resolveConsoleAuth), DashboardService
|
|
10
|
+
+ DashboardError + MediaManagerLike programmatic API, and objectInsights providers.
|
|
11
|
+
Use when mounting or gating the console, wiring console login, building custom admin
|
|
12
|
+
routes over storage, or adding object insights.
|
|
13
|
+
license: MIT
|
|
14
|
+
metadata:
|
|
15
|
+
type: core
|
|
16
|
+
library: "@adonis-agora/media-dashboard"
|
|
17
|
+
library_version: "8.0.0"
|
|
18
|
+
framework: adonisjs
|
|
19
|
+
sources:
|
|
20
|
+
- "DavideCarvalho/adonis-media:docs/dashboard/index.mdx"
|
|
21
|
+
- "DavideCarvalho/adonis-media:docs/dashboard/authentication.mdx"
|
|
22
|
+
- "DavideCarvalho/adonis-media:docs/dashboard/programmatic.mdx"
|
|
23
|
+
- "DavideCarvalho/adonis-media:packages/dashboard/src/index.ts"
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
# The management console
|
|
27
|
+
|
|
28
|
+
The console is a React SPA plus JSON API for browsing buckets, watching resumable uploads,
|
|
29
|
+
and copy/move/delete across buckets. It ships **embedded** in `@adonis-agora/media`
|
|
30
|
+
(`./dashboard_provider`); `@adonis-agora/media-dashboard` is its standalone build source +
|
|
31
|
+
a thin delegate provider for hosts that prefer an explicit install.
|
|
32
|
+
|
|
33
|
+
## Setup
|
|
34
|
+
|
|
35
|
+
```ts title="adonisrc.ts"
|
|
36
|
+
providers: [
|
|
37
|
+
() => import('@adonis-agora/media/media_provider'),
|
|
38
|
+
() => import('@adonis-agora/media/dashboard_provider'),
|
|
39
|
+
]
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
```ts title="config/media_dashboard.ts"
|
|
43
|
+
import { defineConfig } from '@adonis-agora/media/dashboard'
|
|
44
|
+
import { middleware } from '#start/kernel'
|
|
45
|
+
|
|
46
|
+
export default defineConfig({
|
|
47
|
+
basePath: '/media/dashboard',
|
|
48
|
+
actions: true, // copy/move/delete — read-only when false (the default)
|
|
49
|
+
disks: ['s3', 'backups'],
|
|
50
|
+
middleware: middleware.auth(), // gate the whole console — SPA + API
|
|
51
|
+
})
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`node ace configure @adonis-agora/media` registers both providers automatically. The
|
|
55
|
+
`actions`-only routes are always mounted; the gate lives one layer down in
|
|
56
|
+
`DashboardService`, which throws `403` when `actions` is false.
|
|
57
|
+
|
|
58
|
+
Source: `docs/dashboard/index.mdx`.
|
|
59
|
+
|
|
60
|
+
## Core patterns
|
|
61
|
+
|
|
62
|
+
### Pattern 1 — built-in session auth (Mode A / Mode B)
|
|
63
|
+
|
|
64
|
+
`auth` gives the console its own signed cookie so a plain browser navigation works even
|
|
65
|
+
when your app's auth is not cookie-shaped:
|
|
66
|
+
|
|
67
|
+
```ts title="config/media_dashboard.ts"
|
|
68
|
+
import { defineConfig } from '@adonis-agora/media/dashboard'
|
|
69
|
+
|
|
70
|
+
export default defineConfig({
|
|
71
|
+
auth: {
|
|
72
|
+
secret: env.get('MEDIA_CONSOLE_SECRET'), // required — missing/empty is a boot error
|
|
73
|
+
ttl: '8h',
|
|
74
|
+
// Mode A: mint from your app's own auth on the raw request
|
|
75
|
+
async session(request) {
|
|
76
|
+
const token = request.headers.authorization?.replace('Bearer ', '')
|
|
77
|
+
if (!token) return null
|
|
78
|
+
const user = await verifyAccessToken(token)
|
|
79
|
+
return user?.roles.includes('admin') ? { id: String(user.id), roles: user.roles } : null
|
|
80
|
+
},
|
|
81
|
+
// Mode B: validate credentials from the built-in login screen (optional)
|
|
82
|
+
// async login(username, password) { ... },
|
|
83
|
+
async revalidate(user) { // checked at sliding renewal; false ⇒ cookie cleared, 401
|
|
84
|
+
const admin = await Admin.find(Number(user.id))
|
|
85
|
+
return admin !== null && !admin.suspended
|
|
86
|
+
},
|
|
87
|
+
},
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Configure both modes and the login screen offers both (learned from the `401` body of
|
|
92
|
+
`GET /me`). The auth routes (`/me`, `/login`, `/session`, `/logout`) are deliberately mounted
|
|
93
|
+
OUTSIDE both gates — they create the session the guard checks for.
|
|
94
|
+
|
|
95
|
+
Source: `docs/dashboard/authentication.mdx`.
|
|
96
|
+
|
|
97
|
+
### Pattern 2 — reuse the console's engine under your own routes
|
|
98
|
+
|
|
99
|
+
`DashboardService` is framework-free (typed over the structural `MediaManagerLike`), so your
|
|
100
|
+
own admin screens get the same paging and transfer engine:
|
|
101
|
+
|
|
102
|
+
```ts title="start/routes.ts"
|
|
103
|
+
import { MediaManager } from '@adonis-agora/media'
|
|
104
|
+
import { DashboardService, DashboardError } from '@adonis-agora/media/dashboard'
|
|
105
|
+
|
|
106
|
+
const media = await app.container.make(MediaManager)
|
|
107
|
+
const dashboard = new DashboardService(media, { diskNames: ['s3'], actions: true })
|
|
108
|
+
|
|
109
|
+
router.get('/admin/storage/objects', async ({ request, response }) => {
|
|
110
|
+
try {
|
|
111
|
+
return await dashboard.objects(request.input('disk'), {
|
|
112
|
+
prefix: request.input('prefix', ''),
|
|
113
|
+
cursor: request.input('cursor'),
|
|
114
|
+
limit: 100,
|
|
115
|
+
})
|
|
116
|
+
} catch (error) {
|
|
117
|
+
if (error instanceof DashboardError) {
|
|
118
|
+
return response.status(error.status).json({ error: error.message })
|
|
119
|
+
}
|
|
120
|
+
throw error
|
|
121
|
+
}
|
|
122
|
+
}).use([middleware.auth(), middleware.admin()])
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Mutating methods throw `DashboardError(403)` when built with `actions: false`; statuses map
|
|
126
|
+
verbatim onto HTTP (400 invalid argument, 404 unknown disk/record/session, 413 oversized).
|
|
127
|
+
|
|
128
|
+
Source: `docs/dashboard/programmatic.mdx`.
|
|
129
|
+
|
|
130
|
+
### Pattern 3 — object insights annotate previews with YOUR data
|
|
131
|
+
|
|
132
|
+
Providers run on every object preview and render structured data in the lightbox:
|
|
133
|
+
|
|
134
|
+
```ts title="config/media_dashboard.ts"
|
|
135
|
+
export default defineConfig({
|
|
136
|
+
objectInsights: [
|
|
137
|
+
{
|
|
138
|
+
id: 'documents',
|
|
139
|
+
async resolve({ disk, key }) {
|
|
140
|
+
const doc = await Document.findBy('storageKey', key)
|
|
141
|
+
if (!doc) return null
|
|
142
|
+
return {
|
|
143
|
+
title: 'Document',
|
|
144
|
+
facts: [{ label: 'Owner', value: doc.ownerEmail }],
|
|
145
|
+
links: [{ label: 'Open in app', href: `/documents/${doc.id}` }],
|
|
146
|
+
}
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
],
|
|
150
|
+
})
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Providers return data, not components (the SPA is prebuilt); throwing providers are skipped
|
|
154
|
+
and logged; links pass through `sanitizeInsight` (`javascript:`/`data:` hrefs dropped).
|
|
155
|
+
|
|
156
|
+
Source: `docs/dashboard/index.mdx` (Object insights).
|
|
157
|
+
|
|
158
|
+
## Common mistakes
|
|
159
|
+
|
|
160
|
+
### [CRITICAL] Enabling actions without an auth gate
|
|
161
|
+
|
|
162
|
+
Wrong:
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
export default defineConfig({ actions: true }) // no middleware, no auth
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Correct:
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
export default defineConfig({
|
|
172
|
+
actions: true,
|
|
173
|
+
middleware: middleware.auth(),
|
|
174
|
+
auth: { secret: env.get('MEDIA_CONSOLE_SECRET'), login: checkAdminPassword },
|
|
175
|
+
})
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Mechanism: `actions: true` enables copy/move/delete, recursive folder sweeps, record
|
|
179
|
+
deletion, upload aborts and uploads — recursive delete/move are destructive and
|
|
180
|
+
irreversible. The routes are mounted regardless of `enabled`; only `middleware`/`auth`
|
|
181
|
+
keep them from being open to the internet.
|
|
182
|
+
Source: `docs/dashboard/index.mdx` (warn callout, Folder operations warn).
|
|
183
|
+
|
|
184
|
+
### [HIGH] Configuring dashboard auth with neither a session nor a login hook
|
|
185
|
+
|
|
186
|
+
Wrong:
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
auth: { secret: env.get('MEDIA_CONSOLE_SECRET') } // no way to mint a session
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Correct:
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
auth: { secret: env.get('MEDIA_CONSOLE_SECRET'), session: mySessionHook }
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Mechanism: at least one of `session`/`login` must be present — configuring `auth` with
|
|
199
|
+
neither is a boot error by design (a gate nothing can mint a session for would lock the
|
|
200
|
+
console permanently). A hook that THROWS is treated as denial, never a 500.
|
|
201
|
+
Source: `docs/dashboard/authentication.mdx` (The two modes table).
|
|
202
|
+
|
|
203
|
+
### [HIGH] Assuming deleteMediaRecord removes the underlying object
|
|
204
|
+
|
|
205
|
+
Wrong:
|
|
206
|
+
|
|
207
|
+
```ts
|
|
208
|
+
await dashboard.deleteMediaRecord(id) // expecting the bucket to lose the file
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Correct:
|
|
212
|
+
|
|
213
|
+
```ts
|
|
214
|
+
await dashboard.deleteMediaRecord(id) // removes the MediaStore row only
|
|
215
|
+
await dashboard.remove({ disk: 's3', keys: [record.path] }) // remove objects explicitly
|
|
216
|
+
// or delete through the library, which removes original AND conversions:
|
|
217
|
+
await media.library.delete(record.id)
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
Mechanism: `DashboardService.deleteMediaRecord` deletes the metadata row and nothing else —
|
|
221
|
+
the disk object stays where it is, unlike `media.library.delete` which also removes every
|
|
222
|
+
conversion file.
|
|
223
|
+
Source: `docs/dashboard/programmatic.mdx` (Actions table).
|
|
224
|
+
|
|
225
|
+
### [MEDIUM] Registering both the embedded and standalone console providers
|
|
226
|
+
|
|
227
|
+
Wrong:
|
|
228
|
+
|
|
229
|
+
```ts
|
|
230
|
+
providers: [
|
|
231
|
+
() => import('@adonis-agora/media/dashboard_provider'),
|
|
232
|
+
() => import('@adonis-agora/media-dashboard/media_dashboard_provider'), // duplicate
|
|
233
|
+
]
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Correct:
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
providers: [
|
|
240
|
+
() => import('@adonis-agora/media/media_provider'),
|
|
241
|
+
() => import('@adonis-agora/media/dashboard_provider'),
|
|
242
|
+
]
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Mechanism: the standalone provider is a thin delegate to the embedded one — registering both
|
|
246
|
+
mounts the console twice. Register exactly one of the two; both read the same
|
|
247
|
+
`media_dashboard` config key.
|
|
248
|
+
Source: `docs/dashboard/index.mdx` (Standalone install legacy).
|
|
249
|
+
|
|
250
|
+
### [MEDIUM] Running expensive lookups in an objectInsights resolver
|
|
251
|
+
|
|
252
|
+
Wrong:
|
|
253
|
+
|
|
254
|
+
```ts
|
|
255
|
+
async resolve({ key }) {
|
|
256
|
+
const related = await Related.query().where('key', key).preload('everything') // fan-out
|
|
257
|
+
return { facts: related.map(...) }
|
|
258
|
+
}
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
Correct:
|
|
262
|
+
|
|
263
|
+
```ts
|
|
264
|
+
async resolve({ key }) {
|
|
265
|
+
const doc = await Document.findBy('storageKey', key) // single indexed lookup
|
|
266
|
+
return doc ? { facts: [{ label: 'Owner', value: doc.ownerEmail }] } : null
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
Mechanism: `resolve` runs on EVERY preview of EVERY object (providers concurrently,
|
|
271
|
+
failures skipped and logged) — annotation must never slow opening a file, so keep it to one
|
|
272
|
+
indexed lookup.
|
|
273
|
+
Source: `docs/dashboard/index.mdx` (Object insights).
|
|
274
|
+
|
|
275
|
+
See also: `media-stores-delivery/SKILL.md` — the ExtendedDisk operations and
|
|
276
|
+
`MediaStore.list` the console consumes; `media-react-uploads/SKILL.md` — the upload client
|
|
277
|
+
and console launcher it embeds.
|