Programmatic API

The console's provider is a thin HTTP shell. Every read and every action it performs lives in DashboardService — a plain class, no AdonisJS import anywhere in it, expressed over a structural view of the media manager. That is what makes the console's logic unit-testable without booting an app, and it is also what lets you reuse it.

Reach for this when you want the console's behaviour under your own routes: a bespoke admin screen, an internal API that lists buckets, a CLI that sweeps a prefix. You get the real implementation — the same paging, the same cross-disk transfer engine, the same guards — instead of a re-derivation of it.

import { DashboardService, DashboardError } from '@adonis-agora/media/dashboard'
import type { MediaManagerLike, DashboardServiceOptions } from '@adonis-agora/media/dashboard'

Constructing one

import { MediaManager } from '@adonis-agora/media'
import { DashboardService } from '@adonis-agora/media/dashboard'

const media = await app.container.make(MediaManager)

const dashboard = new DashboardService(
  media,                                    // any MediaManagerLike
  { diskNames: ['s3', 'backups'], actions: true },
  [documentInsightProvider],                // optional — ObjectInsightProvider[]
)

Three arguments:

1. the manager — typed MediaManagerLike, not MediaManager. The real manager satisfies it; so does a hand-rolled fake (see below).
2. DashboardServiceOptions — { diskNames, actions }. The first disk name (or the manager's default) is the default disk; actions: false makes every mutating method throw 403.
3. insightProviders — the object-insight providers, defaulting to [].

MediaManagerLike

The exact slice of MediaManager the console depends on — deliberately small, so faking it in a test is a few lines:

interface MediaManagerLike {
  readonly storage: { readonly defaultDisk: string; disk(name?: string): Disk }
  readonly hasResumable: boolean
  readonly resumable: {
    list(filter?: { disk?: string; keyPrefix?: string }): Promise<UploadSession[]>
    abort(id: string): Promise<void>
    listParts(id: string): Promise<MultipartPart[]>
  }
  readonly store: {
    list(options?: MediaListOptions): Promise<MediaListPage>
    find(id: string): Promise<MediaRecord | null>
    delete(id: string): Promise<void>
  }
}

Note what is not there: nothing about attaching, converting or transforming. The console reads and moves objects; it never creates media.

The methods

Reads

Cursor pagination

objects and collections take { after?, first? } and return a cursor page — the interface every @adonis-agora/* library paginates through (mirroring @adonis-agora/filter's CursorParams / CursorPage structurally; there is no dependency on that package).

let after: string | undefined
do {
  const page = await dashboard.objects('s3', { prefix: 'photos/', first: 100, ...(after ? { after } : {}) })
  handle(page.folders, page.files)
  after = page.nextCursor ?? undefined
} while (after !== undefined)

collections returns CursorPage<MediaEntry> verbatim (items + the envelope). objects carries the same envelope but keeps two payload arrays — folders (common prefixes) and files — because a delimiter listing yields both in one page and collapsing them into a single items array would lose the distinction; its type is therefore CursorPageInfo & { folders, files }.

Actions

Every method below calls assertActions() first and throws DashboardError(403) when the service was built with actions: false.

DashboardError

One error type, carrying the HTTP status the provider surfaces verbatim:

class DashboardError extends Error {
  constructor(message: string, readonly status: number)
}

400 for a missing/invalid argument, 403 for an actions-gated call on a read-only service, 404 for an unknown disk / record / session, 413 for an oversized upload. Anything else that escapes is a genuine bug and reaches your handler as-is — the provider maps a non-DashboardError to 500.

Using it in your own route

router
  .get('/admin/storage/objects', async ({ request, response }) => {
    try {
      return await dashboard.objects(request.input('disk'), {
        prefix: request.input('prefix', ''),
        after: request.input('after'),
        first: 100,
      })
    } catch (error) {
      if (error instanceof DashboardError) {
        return response.status(error.status).json({ error: error.message })
      }
      throw error
    }
  })
  .use([middleware.auth(), middleware.admin()])

Note the shape of that error handling — it is exactly what the provider does internally, and it is the whole contract: catch DashboardError, use its status, rethrow everything else.

The JSON contract types

Every response shape the API returns is exported as a type, framework-free (no DOM, no Node), so the same declarations type both a server handler and a browser client. They live in two places with identical content:

// from the core package — alongside DashboardService
import type { DiskInfo, ObjectListResponse, MediaEntry } from '@adonis-agora/media/dashboard'

// from the standalone dashboard package — for a browser bundle that shouldn't pull in the server
import type { DiskInfo, ObjectListResponse, MediaEntry } from '@adonis-agora/media-dashboard/types'

The second subpath is the one to import from a frontend: it carries only these declarations, with no server code behind it.

Two projections are worth reading carefully. MediaEntry.conversions is a list of names, not the conversion objects — the console shows which derivatives exist, and mediaRecord(id) is where you get their URLs. And every timestamp crosses as an ISO-8601 string, because these shapes travel over JSON; nothing here is a Date.

Next steps

• Dashboard — the console's config, routes and views
• Console authentication — the session gate in front of all of this
• Collections view — the MediaStore.list contract behind collections()