React Client

@adonis-agora/media-react is the first-party browser companion to the server upload routes. It speaks the AdonisJS provider's actual HTTP contract across all three strategies:

• TUS resumable (default) — POST / HEAD / PATCH / DELETE against tusPath (default /media/uploads/tus, matching uploads.resumable.routes.prefix), resuming from the server's Upload-Offset.
• Direct-S3 multipart — the direct-session contract against directPath (default /media/uploads/direct/sessions, matching uploads.direct.routes.prefix): POST {directPath} initiates and returns presigned part URLs, each part PUTs straight to S3, POST {directPath}/:id/parts/:partNumber confirms its ETag, and POST {directPath}/:id/complete assembles the object. GET {directPath}/:id reports a session's state and DELETE {directPath}/:id tears it down.
• Proxy — a single PUT {uploadsPath}/proxy streams the whole body through the app.

createMediaUploadClient({ directPath: '/api/v1/upload-video' })

The older stateless routes under uploads.routes.prefix (POST /direct/initiate, POST /direct/:uploadId/complete) exist too, but this client does not speak them. They are the raw primitives documented in Upload modes; the client always uses the session-backed contract, because that is the one that survives a page reload.

useMediaUpload

A hook with progress / status state and pause / resume / abort. For tus, resume continues from the server offset; for direct / proxy a resume restarts the transfer.

import { useMediaUpload } from '@adonis-agora/media-react'

function Uploader() {
  const { upload, pause, resume, abort, status, progress } = useMediaUpload({ mode: 'tus' })

  return (
    <div>
      <input
        type="file"
        onChange={(e) => {
          const file = e.target.files?.[0]
          if (file) upload(file, { filename: file.name, contentType: file.type })
        }}
      />
      <progress value={progress} max={1} />
      <span>{status}</span>
    </div>
  )
}

• mode: 'tus' (resumable, default) · 'direct' (presigned S3 multipart) · 'proxy'.
• State: status ('idle' | 'uploading' | 'paused' | 'success' | 'error'), progress (0..1), result, location (TUS session), error, resumable (see below).
• Actions: upload(file, meta), pause(), resume(), abort() (terminates the session server-side), reset().
• Only proxy takes a key in the upload meta. TUS and direct both derive the key server-side, and meta.key is ignored on those paths — a client-chosen key would be a hole you'd have to close anyway.

The hook accepts every MediaUploadClientOptions field (below) plus an optional pre-built client for tests or a shared instance, and a storageKey for cross-reload resume.

The typed completion body

useMediaUpload<TComplete>() types what the server's complete returned. For a direct upload with a DirectUploadPolicy, that body is whatever the policy's onComplete handed back — a media id, a status, a whole domain object:

type Completion = { mediaId: string; status: 'processing' }

const { upload } = useMediaUpload<Completion>({ mode: 'direct' })

const result = await upload(file, { filename: file.name, contentType: file.type })
if (result.mode === 'direct') {
  router.visit(`/videos/${result.body.mediaId}`) // typed
}

The result is a discriminated union — { mode: 'tus', location }, { mode: 'direct', uploadId, key, disk, body }, { mode: 'proxy', key, disk } — so narrowing on mode is what gets you to body at all.

Pausing and resuming

pause() aborts the in-flight transfer and settles into status: 'paused'; resume() picks the same file back up. What "resume" means depends on the strategy:

• tus — a true byte-offset resume. The client re-HEADs the session, learns the server's offset, and continues from exactly there.
• direct — a real resume at part granularity. pause aborts the in-flight part PUTs; resume calls directSessionStatus and continues from the session's still-pending parts with fresh presigned URLs. Parts already confirmed are never re-uploaded.
• proxy — a single-shot transfer, so a resume restarts it.

abort() differs from reset() in one important way: abort tears the session down server-side (a TUS DELETE, a direct-session DELETE) as well as clearing local state, while reset only clears locally. Reset an upload you might resume; abort one you are done with.

Resuming a direct upload across a reload

Pause/resume survives a component unmount but not a page reload — the session coordinates live in memory. Pass storageKey and they are persisted to localStorage on initiate:

const { upload, resume, resumable, status, progress } = useMediaUpload({
  mode: 'direct',
  storageKey: `upload:lesson:${lessonId}`,
})

return resumable ? (
  <button type="button" onClick={() => resume()}>
    Resume “{resumable.fileName}”
  </button>
) : (
  <input type="file" onChange={(e) => { /* upload(file, meta) */ }} />
)

How it behaves, because the details are what make it trustworthy:

• On mount, the hook probes the persisted session. If the server still has pending parts, resumable is populated with { uploadId, fileName } — your cue to offer "resume" instead of "choose a file". If the session is finished or gone, the entry is dropped silently.
• On upload() of the same file, a persisted session is reused when the file name and the byte size both match. Requiring the size too is what stops a revised same-named file from splicing its bytes into the old session.
• The server is the authority. On resume the client re-reads the coordinates from directSessionStatus — key, disk, part size, pending parts — rather than trusting the stored copy.
• A definitive "gone" (404 / 410) drops the entry and falls through to a fresh initiate, so an expired session never bricks that storageKey. A transient failure (network blip, 5xx) keeps the entry resumable and surfaces the error instead of silently discarding progress and restarting at 0%. Telling those two apart is exactly what MediaHttpError.status is for.
• The entry is cleared on success, on abort() and on reset().

Because resume() needs the original Blob back, offer it from a control that still has the file (or re-prompt for it) — the hook persists the session's coordinates, never the bytes. storageKey is ignored by tus and proxy, and should be unique per upload slot: two uploaders sharing one key would fight over the same entry.

MediaUploader

A minimal, headless-friendly component wired to the hook. The default markup is a file input + progress bar; pass render to take full control.

import { MediaUploader } from '@adonis-agora/media-react'

<MediaUploader mode="tus" accept="image/*" onUploaded={(r) => console.log(r)} />

// Fully headless — bring your own UI:
<MediaUploader
  mode="direct"
  render={({ status, progress, selectFile }) => (
    /* your markup; call selectFile(file) to start */
  )}
/>

The default styling uses Agora design tokens (--agora-primary, --agora-primary-soft, --agora-ink) through overridable --agora-media-* CSS custom properties — retheme by setting a variable, or pass unstyled to drop the stylesheet. No vendor branding. (ensureMediaUploaderStyles / mediaUploaderCss / MEDIA_UPLOADER_STYLE_ID are exported if you manage the stylesheet yourself.)

createMediaUploadClient (framework-free)

The ./client entry point needs no React and drives the same three strategies directly.

import { createMediaUploadClient } from '@adonis-agora/media-react/client'

const client = createMediaUploadClient({
  baseUrl: 'https://api.example.com',
  headers: { Authorization: `Bearer ${token}` },     // merged into every app request
  getHeaders: async () => ({ Authorization: `Bearer ${await fresh()}` }), // short-lived tokens
})

await client.uploadTus(file, { filename: 'a.png', contentType: 'image/png' })
await client.uploadDirect(file, { filename: 'a.png', contentType: 'image/png' }) // key: server-side
await client.uploadProxy(file, { filename: 'a.png', key: 'u/1/a.png' })          // key: required

Those are the three upload entry points; the client also exposes the session primitives underneath them (createTusSession, tusOffset, abortTus, directSessionStatus, abortDirectSession) and an injectable part transport. See Upload client for the full surface.

UploadMeta

A mediaUrl(id, conversion?) helper is also exported for composing URLs against the base path.

Next steps

• Upload client — the full MediaUploadClient surface, the part transport, and MediaHttpError
• Console launcher — open the media console from your app, in three tiers
• Direct sessions — the server contract the direct strategy speaks
• Resumable / TUS — the TUS protocol it implements
• Dashboard — reuses this client for its upload UI