@adonis-agora/media-dashboard 8.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 CHANGED
@@ -1,5 +1,14 @@
1
1
  # @adonis-agora/media-dashboard
2
2
 
3
+ ## 8.0.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#57](https://github.com/DavideCarvalho/adonis-agora-media/pull/57) [`331f53f`](https://github.com/DavideCarvalho/adonis-agora-media/commit/331f53f6294f3b7e4261bdbf65fb8090063aa673) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Ship TanStack Intent agent skills with every package. Each package now publishes a
8
+ `skills/` directory (`media-*` SKILL.md files) that lands in `node_modules` on install, so
9
+ AI coding agents can discover them via `npx @tanstack/intent list`; adds `@tanstack/intent`
10
+ as a devDependency for `intent validate` in CI.
11
+
3
12
  ## 8.0.0
4
13
 
5
14
  ### Patch Changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adonis-agora/media-dashboard",
3
- "version": "8.0.0",
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,7 +32,8 @@
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": {
@@ -61,7 +62,8 @@
61
62
  "typescript": "^5.4.0",
62
63
  "vite": "^6.0.0",
63
64
  "vitest": "3.2.7",
64
- "@adonis-agora/media-react": "0.5.0"
65
+ "@tanstack/intent": "^0.3.2",
66
+ "@adonis-agora/media-react": "0.5.1"
65
67
  },
66
68
  "engines": {
67
69
  "node": ">=20.6.0"
@@ -77,7 +79,8 @@
77
79
  "buckets",
78
80
  "upload",
79
81
  "resumable",
80
- "agora"
82
+ "agora",
83
+ "tanstack-intent"
81
84
  ],
82
85
  "scripts": {
83
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.