@adonis-agora/media 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @adonis-agora/media
 
+## 0.12.2
+
+### Patch Changes
+
+- [#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
+  `skills/` directory (`media-*` SKILL.md files) that lands in `node_modules` on install, so
+  AI coding agents can discover them via `npx @tanstack/intent list`; adds `@tanstack/intent`
+  as a devDependency for `intent validate` in CI.
+
+## 0.12.1
+
+### Patch Changes
+
+- [#52](https://github.com/DavideCarvalho/adonis-agora-media/pull/52) [`4d9651d`](https://github.com/DavideCarvalho/adonis-agora-media/commit/4d9651d29863f2823f426a38588305528e8da699) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - **Fixes a hard `npm install` failure.** Two peer ranges used a caret over a 0.x dependency, which under semver does not cross a minor — `^0.4.0` means `>=0.4.0 <0.5.0`. Every later minor of those peers fell out of range.
+
+  pnpm downgrades an unsatisfied peer to a warning, so this was invisible inside the monorepo. **npm treats it as `ERESOLVE` and refuses to install**, even though both peers are declared optional:
+
+  ```
+  While resolving: @adonis-agora/media@0.12.0
+  Found: @adonis-agora/telescope@0.8.1
+  Conflicting peer dependency: @adonis-agora/telescope@0.4.0
+  ```
+
+  - `@adonis-agora/telescope`: `^0.4.0` → `>=0.4.0 <1.0.0`. Telescope is at 0.8.1, so any consumer on a current telescope could not install this package under npm. The floor stays at 0.4.0: bisecting the published tarballs shows the extension contract `mediaTelescopeExtension()` implements has been type-compatible since 0.1.0, so 0.4.0 was never too high — only the ceiling was wrong.
+  - `sharp`: `^0.33.0` → `>=0.33.0 <1.0.0`. Same defect, same `ERESOLVE`; sharp is at 0.35.3. The processor only uses `resize`/`toFormat`/`quality`/`toBuffer`, verified end to end against sharp 0.35.3 outside the monorepo.
+
+  No runtime behaviour changes, and no dependency is bumped — this only widens what a consumer is _allowed_ to have installed.
+
 ## 0.12.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/media",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Media-library for AdonisJS — owner collections (MIME whitelist, single-file replace, ordering), image conversions (eager/lazy), pluggable content transformers (HLS video via mediabunny, metadata probe), and column attachments, all on top of @adonisjs/drive. Pluggable MediaStore (in-memory + Lucid) and ImageProcessor (sharp). Part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -87,17 +87,18 @@
   "files": [
     "dist/",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "skills"
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@adonis-agora/telescope": "^0.4.0",
+    "@adonis-agora/telescope": ">=0.4.0 <1.0.0",
     "@adonisjs/core": "^7.3.0",
     "@adonisjs/drive": "^3.0.0 || ^4.0.0",
     "@adonisjs/lucid": "^22.4.0",
     "@aws-sdk/client-s3": "^3.0.0",
     "mediabunny": "^1.45.4",
-    "sharp": "^0.33.0"
+    "sharp": ">=0.33.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@adonis-agora/telescope": {
@@ -133,8 +134,9 @@
     "tempura": "0.4.1",
     "typescript": "^5.4.0",
     "vitest": "3.2.7",
-    "@adonis-agora/media-react": "0.5.0",
-    "@adonis-agora/media-dashboard": "8.0.0"
+    "@tanstack/intent": "^0.3.2",
+    "@adonis-agora/media-dashboard": "8.0.1",
+    "@adonis-agora/media-react": "0.5.1"
   },
   "engines": {
     "node": ">=20.6.0"
@@ -155,11 +157,12 @@
     "mediabunny",
     "sharp",
     "attachment",
-    "agora"
+    "agora",
+    "tanstack-intent"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json && pnpm run copy:stubs",
-    "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations dist/assets && cp stubs/config/media.stub dist/stubs/config/media.stub && cp stubs/config/media_dashboard.stub dist/stubs/config/media_dashboard.stub && cp -r stubs/database/migrations/. dist/stubs/database/migrations/ && rm -rf dist/assets/spa && cp -r ../dashboard/dist/spa dist/assets/spa",
+    "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations dist/assets && cp -r stubs/config/. dist/stubs/config/ && cp -r stubs/database/migrations/. dist/stubs/database/migrations/ && rm -rf dist/assets/spa && cp -r ../dashboard/dist/spa dist/assets/spa",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit"

package/skills/media-attachments-single-file/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: media-attachments-single-file
+description: >-
+  Column attachments and the single-file seam in @adonis-agora/media —
+  AttachmentManager.createFromFile with always-eager image variants, the Attachment
+  value object (toJSON / Attachment.fromJSON), persisting to a Lucid JSON column with
+  prepare/consume, media.attachments.url/signedUrl/delete semantics, and
+  @adonis-agora/media/single-file (storeSingleFile, removeSingleFile,
+  isSingleFileStoreAvailable, storeSingleFileWith) so other packages can delegate
+  avatar-style uploads without a hard dependency. Use when a model "has a file"
+  (avatar, hero image, logo) or when wiring cross-package single-file uploads.
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/media"
+  library_version: "0.12.1"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-media:docs/attachments.mdx"
+  - "DavideCarvalho/adonis-media:docs/single-file.mdx"
+  - "DavideCarvalho/adonis-media:packages/adonis/src/attachment.ts"
+  - "DavideCarvalho/adonis-media:packages/adonis/src/single_file_store.ts"
+---
+
+# Column attachments & the single-file seam
+
+Two shapes share one storage layer. The `MediaLibrary` is owner+collections; the
+`AttachmentManager` is the adonis-attachment style — one file living **directly on a model
+column** as a JSON value, no owner row, no extra table. Reach for an attachment when a model
+simply *has* a file (an avatar, a hero image); reach for collections when an entity has many
+files with policy.
+
+## Setup
+
+```ts title="app/controllers/avatars_controller.ts"
+import { createReadStream } from 'node:fs'
+import User from '#models/user'
+import media from '@adonis-agora/media/services/main'
+import type { HttpContext } from '@adonisjs/core/http'
+
+export default class AvatarsController {
+  async update({ request, response, auth }: HttpContext) {
+    const user = auth.getUserOrFail()
+
+    const avatar = request.file('avatar', { size: '2mb', extnames: ['jpg', 'jpeg', 'png', 'webp'] })
+    if (!avatar) return response.badRequest({ error: 'An "avatar" file is required' })
+
+    const att = await media.attachments.createFromFile(
+      {
+        fileName: avatar.clientName,
+        mimeType: avatar.type!,
+        contents: createReadStream(avatar.tmpPath!), // Buffer | Readable
+      },
+      { variants: [{ name: 'thumb', width: 100 }] },
+    )
+
+    user.avatarData = att.toJSON() // store on a JSON column
+    await user.save()
+
+    return response.ok(user)
+  }
+}
+```
+
+The file lands at `${keyPrefix}/${id}/${fileName}` (`keyPrefix` defaults to your
+`attachmentKeyPrefix`, default `attachments`), variants at
+`${keyPrefix}/${id}/variants/${name}.${format}`.
+
+Source: `docs/attachments.mdx` (Creating an attachment).
+
+## Core patterns
+
+### Pattern 1 — serialize onto a Lucid JSON column
+
+An `Attachment` is a pure JSON-serializable value object (disk, path, size, mimeType,
+variants, meta). Persist `toJSON()`, rebuild with `Attachment.fromJSON()`:
+
+```ts title="app/models/user.ts"
+import { BaseModel, column } from '@adonisjs/lucid/orm'
+import { Attachment, type AttachmentData } from '@adonis-agora/media'
+
+export default class User extends BaseModel {
+  @column({
+    prepare: (v) => (v ? JSON.stringify(v) : v),
+    consume: (v) => (typeof v === 'string' ? JSON.parse(v) : v),
+  })
+  declare avatarData: AttachmentData | null
+
+  get avatar(): Attachment | null {
+    return Attachment.fromJSON(this.avatarData)
+  }
+}
+```
+
+Source: `docs/attachments.mdx` (A model-column pattern).
+
+### Pattern 2 — resolve URLs and signed URLs through the manager
+
+The value object never touches storage; URL resolution and deletion go through
+`media.attachments`:
+
+```ts
+const att = Attachment.fromJSON(user.avatarData)!
+
+await media.attachments.url(att)            // original
+await media.attachments.url(att, 'thumb')   // named variant
+
+await media.attachments.signedUrl(att, '30m')                        // expiring (s3/gcs)
+await media.attachments.signedUrl(att, '1h', { variant: 'thumb' })   // signed variant
+
+// force a named download — headers are baked into the URL by the presigner
+await media.attachments.signedUrl(att, '1h', {
+  contentDisposition: `attachment; filename="${att.name}"`,
+})
+```
+
+Source: `docs/attachments.mdx` (Resolving URLs).
+
+### Pattern 3 — the single-file store for other packages
+
+`@adonis-agora/media/single-file` is the narrow seam for "replace this owner's one file and
+give me a URL", importable unconditionally with feature detection:
+
+```ts
+import { isSingleFileStoreAvailable, removeSingleFile, storeSingleFile } from '@adonis-agora/media/single-file'
+
+if (await isSingleFileStoreAvailable()) {
+  const { url, thumbUrl } = await storeSingleFile({
+    ownerType: 'User',
+    ownerId: String(user.id),
+    collection: 'avatar',
+    fileName: upload.clientName,
+    mimeType: upload.type!,
+    contents: upload.bytes, // a Buffer
+  })
+  // thumbUrl is null — not an error — when the 'thumb' conversion isn't configured
+}
+
+// tests or multi-manager apps pass the manager explicitly:
+import { storeSingleFileWith } from '@adonis-agora/media/single-file'
+await storeSingleFileWith(testManager, { ownerType: 'User', ownerId: '1', collection: 'avatar',
+  fileName: 'me.png', mimeType: 'image/png', contents: pngBytes })
+```
+
+`removeSingleFile({ ownerType, ownerId, collection })` empties the owner's collection,
+deleting each record's disk object and conversions.
+
+Source: `docs/single-file.mdx`.
+
+## Common mistakes
+
+### [HIGH] Requesting attachment variants that were not declared up front
+
+Wrong:
+
+```ts
+const att = await media.attachments.createFromFile(input) // no variants option
+await media.attachments.url(att, 'thumb') // throws
+```
+
+Correct:
+
+```ts
+const att = await media.attachments.createFromFile(input, {
+  variants: [{ name: 'thumb', width: 100 }],
+})
+await media.attachments.url(att, 'thumb')
+```
+
+Mechanism: unlike the library's lazy conversions, attachment **variants are always eager** —
+generated inside `createFromFile`, because there is no per-attachment record to cache a
+lazily-generated variant onto. An undeclared variant throws `VariantNotFoundError`
+(`E_MEDIA_VARIANT_NOT_FOUND`). Requesting any variant with no `imageProcessor` configured
+throws.
+Source: `docs/attachments.mdx` (Variants are eager callout, Resolving URLs).
+
+### [HIGH] Leaving the model column populated after attachments.delete()
+
+Wrong:
+
+```ts
+await media.attachments.delete(att)
+// column still holds the JSON → every url()/signedUrl() resolves deleted objects
+```
+
+Correct:
+
+```ts
+await media.attachments.delete(att)
+user.avatarData = null
+await user.save()
+```
+
+Mechanism: `delete()` removes the original AND every variant from storage but deliberately
+does not touch your model column — clearing it is yours, since only you know the field.
+Stale columns keep producing dead URLs until saved as null.
+Source: `docs/attachments.mdx` (Deleting).
+
+### [CRITICAL] Calling storeSingleFile against a collection that is not single:true
+
+Wrong:
+
+```ts
+// config declares NO 'avatar' collection (or declares it without single: true)
+await storeSingleFile({ ownerType: 'User', ownerId: '1', collection: 'avatar', ... }) // upload #1
+await storeSingleFile({ ownerType: 'User', ownerId: '1', collection: 'avatar', ... }) // upload #2
+```
+
+Correct:
+
+```ts
+// config/media.ts
+defineConfig({
+  collections: [{ name: 'avatar', single: true, acceptsMimeTypes: ['image/png', 'image/jpeg'] }],
+})
+```
+
+Mechanism: nothing about these functions enforces replacement — replacement is a property of
+the COLLECTION. Without `single: true` each call appends another record, and "the avatar"
+quietly becomes a growing list of files.
+Source: `docs/single-file.mdx` (warn callout: `single: true` lives in the config).
+
+See also: `media-library-collections/SKILL.md` — choosing between the two shapes and the
+collection policy both paths run under.

package/skills/media-library-collections/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: media-library-collections
+description: >-
+  Attach files to owner collections with @adonis-agora/media — media.library.attach /
+  attachExisting / for(ownerType, ownerId), the MediaCollectionConfig policy layer
+  (acceptsMimeTypes exact-match whitelist plus magic-byte signature verification,
+  single:true atomic replace, append-only ordering, per-collection disk), eager vs lazy
+  ConversionPresets (width/height/fit/format/quality, webp default), ensureConversion,
+  url/signedUrl resolution, delete semantics, deterministic id retries, customProperties,
+  and the MediaRecord.conversions map shared with transformers. Use when uploading files
+  to entities, defining collections, generating thumbnails, or fixing
+  MimeNotAllowedError / ConversionNotDefinedError / ImageProcessorMissingError /
+  TransformNotReadyError.
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/media"
+  library_version: "0.12.1"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-media:docs/getting-started.mdx"
+  - "DavideCarvalho/adonis-media:docs/collections-and-conversions.mdx"
+  - "DavideCarvalho/adonis-media:docs/transformers.mdx"
+  - "DavideCarvalho/adonis-media:packages/adonis/src/media_library.ts"
+---
+
+# Media library: collections, policy, and conversions
+
+`media.library` is the spatie/laravel-media-library shape: files belong to an owner
+(`ownerType` + `ownerId`, both just stored strings — the library never loads your models)
+inside named collections that carry the policy. Attach writes bytes to a Drive disk and a
+metadata record to the configured `MediaStore`.
+
+## Setup
+
+```ts title="app/controllers/post_images_controller.ts"
+import { createReadStream } from 'node:fs'
+import Post from '#models/post'
+import media from '@adonis-agora/media/services/main'
+import type { HttpContext } from '@adonisjs/core/http'
+
+export default class PostImagesController {
+  async store({ request, response, params }: HttpContext) {
+    const post = await Post.findOrFail(params.id)
+
+    const image = request.file('image', { size: '5mb', extnames: ['jpg', 'png', 'webp'] })
+    if (!image) return response.badRequest({ error: 'An "image" file is required' })
+
+    const record = await media.library.attach({
+      ownerType: 'Post',
+      ownerId: post.id, // string | number — coerced for you
+      collection: 'gallery',
+      fileName: image.clientName,
+      mimeType: image.type!,
+      contents: createReadStream(image.tmpPath!), // Buffer | Readable
+    })
+
+    return response.created({ id: record.id, url: await media.library.url(record.id) })
+  }
+}
+```
+
+The file lands at `${ownerType}/${ownerId}/${collection}/${id}/${fileName}` on the resolved
+disk (per-call `disk` → collection `disk` → storage default). Eager conversions are
+generated synchronously inside `attach`; lazy ones wait for the first `url(id, name)`.
+
+Source: `docs/getting-started.mdx` (Step 3).
+
+## Core patterns
+
+### Pattern 1 — declare the collection policy in config
+
+Collections are opt-in constraints: an undeclared collection is permissive (no whitelist,
+not single, no conversions). Declare one to constrain it:
+
+```ts title="config/media.ts"
+defineConfig({
+  collections: [
+    { name: 'avatar', single: true, acceptsMimeTypes: ['image/png', 'image/jpeg'] },
+    { name: 'invoices', disk: 'private-s3', acceptsMimeTypes: ['application/pdf'] },
+    {
+      name: 'gallery',
+      conversions: [
+        { name: 'thumb', width: 200, height: 200, fit: 'cover' },
+        { name: 'card', width: 600, format: 'webp', quality: 80 },
+        { name: 'og', width: 1200, height: 630, eager: true },
+      ],
+    },
+  ],
+})
+```
+
+`acceptsMimeTypes` is checked **before anything is written** (no orphan files on rejection)
+and is an exact string match — list each type. When a whitelist is present the library also
+verifies the file's magic-byte signature: a mismatch throws `ContentTypeMismatchError`, and
+on a **closed** whitelist (every accepted type is signature-detectable, e.g.
+`['application/pdf']`) unrecognizable bytes throw `ContentSignatureUnrecognizedError`. An
+**open** whitelist (any type without a signature, e.g. `['application/pdf', 'image/svg+xml']`)
+falls back to the declared type.
+
+Source: `docs/collections-and-conversions.mdx`.
+
+### Pattern 2 — eager vs lazy conversions
+
+`ConversionPreset` maps straight onto sharp. `eager: true` generates synchronously on
+`attach`; the default is lazy — generated on the **first** `url(id, name)` and then cached on
+the record, so every later call is a pure lookup.
+
+```ts
+const m = await media.library.attach({ ...input, collection: 'gallery' })
+
+await media.library.url(m.id, 'og')    // eager → already on disk, pure lookup
+await media.library.url(m.id, 'thumb') // lazy → generated NOW, then cached
+await media.library.ensureConversion(m.id, 'thumb') // force it ahead of time (idempotent)
+```
+
+Conversions are written under `conversions/` next to the original, recorded on
+`record.conversions` keyed by preset name, and removed by `delete()` together with the
+original. `format` defaults to `webp`; `fit` defaults to `cover`.
+
+Source: `docs/collections-and-conversions.mdx` (Eager vs lazy).
+
+### Pattern 3 — bind an owner once with `for()`, adopt existing objects with `attachExisting`
+
+```ts
+const gallery = media.library.for('Post', post.id)
+
+for (const image of images) {
+  await gallery.attach({ collection: 'gallery', fileName: image.clientName, mimeType: image.type!, contents })
+}
+
+// zero-copy adoption of an object ALREADY on the disk (finished TUS / direct upload):
+await gallery.attachExisting({
+  collection: 'gallery',
+  key: 'uploads/9f2a/clip.mp4',
+  fileName: 'clip.mp4',
+  mimeType: 'video/mp4',
+})
+```
+
+`attachExisting` never reads or rewrites bytes; the size comes from a disk HEAD when
+omitted, and the collection's MIME + signature checks still run against a short head read.
+Pass `moveIntoLayout: true` to relocate into the canonical layout using the disk's native
+server-side move.
+
+Source: `docs/getting-started.mdx` (Bind an owner once), `docs/uploads/resumable-tus.mdx`.
+
+### Pattern 4 — deterministic `id` for retry-safe overwrites
+
+```ts
+await media.library.attach({
+  ownerType: 'Invoice',
+  ownerId: invoice.id,
+  collection: 'pdf',
+  id: `invoice-${invoice.id}`, // fixed key → retry-safe overwrite, no orphaned UUIDs
+  fileName: 'invoice.pdf',
+  mimeType: 'application/pdf',
+  contents: renderedPdf,
+})
+```
+
+The `id` is used verbatim as the record key and the storage-key segment — you own
+uniqueness. Retries overwrite in place instead of minting a fresh UUID path.
+
+Source: `docs/getting-started.mdx` (Idempotent overwrites).
+
+## Common mistakes
+
+### [CRITICAL] Assuming attach replaces an existing file without single:true
+
+Wrong:
+
+```ts
+// 'avatar' declared WITHOUT single: true — each call appends another file
+await media.library.attach({ ownerType: 'User', ownerId: '1', collection: 'avatar', ... }) // v1
+await media.library.attach({ ownerType: 'User', ownerId: '1', collection: 'avatar', ... }) // v2
+await media.library.list('User', '1', 'avatar') // [v1, v2] — "the avatar" is now a list
+```
+
+Correct:
+
+```ts
+// config/media.ts
+defineConfig({ collections: [{ name: 'avatar', single: true, acceptsMimeTypes: ['image/png'] }] })
+```
+
+Mechanism: replacement is a property of the **collection**, not the call. `single: true`
+deletes the previous file (original + conversions) only AFTER the new one is safely
+persisted, so a failed upload leaves the old media intact; without it ordering is
+append-only and every attach takes the next slot.
+Source: `docs/collections-and-conversions.mdx` (Single-file collections), `docs/single-file.mdx` (warn callout).
+
+### [HIGH] Using wildcard MIME types in acceptsMimeTypes
+
+Wrong:
+
+```ts
+defineConfig({
+  collections: [{ name: 'images', acceptsMimeTypes: ['image/*'] }],
+})
+```
+
+Correct:
+
+```ts
+defineConfig({
+  collections: [{ name: 'images', acceptsMimeTypes: ['image/png', 'image/jpeg', 'image/webp'] }],
+})
+```
+
+Mechanism: the whitelist is an exact string match against the declared `mimeType` — there is
+no wildcard expansion, so `'image/*'` matches nothing and every attach throws
+`MimeNotAllowedError` (`E_MEDIA_MIME_NOT_ALLOWED`) before anything is written.
+Source: `docs/collections-and-conversions.mdx` (MIME whitelist).
+
+### [HIGH] Requesting conversions with no imageProcessor configured
+
+Wrong:
+
+```ts
+defineConfig({
+  collections: [{ name: 'gallery', conversions: [{ name: 'thumb', width: 200 }] }],
+  // no imageProcessor
+})
+```
+
+Correct:
+
+```ts
+import { defineConfig, processors } from '@adonis-agora/media'
+
+defineConfig({
+  imageProcessor: processors.sharp(),
+  collections: [{ name: 'gallery', conversions: [{ name: 'thumb', width: 200 }] }],
+})
+```
+
+Mechanism: `imageProcessor` is required only when conversions exist, but asking for one
+without a configured processor throws `ImageProcessorMissingError`
+(`E_MEDIA_IMAGE_PROCESSOR_MISSING`) instead of silently skipping.
+Source: `docs/configuration.mdx` (`imageProcessor`), `docs/errors.mdx`.
+
+### [CRITICAL] Reading url() on a transformer conversion expecting lazy generation
+
+Wrong:
+
+```ts
+// 'videos' collection declares transformers.hls()
+const url = await media.library.url(videoId, 'hls') // throws before any transform ran
+```
+
+Correct:
+
+```ts
+// run the transform explicitly (usually from a job), then read
+await media.library.transform(videoId, 'hls') // idempotent — retries skip through
+const record = await media.library.find(videoId)
+record!.conversions.hls // { path, prefix, files, meta }
+```
+
+Mechanism: image presets generate lazily on first read, but reads NEVER generate transforms —
+`url()`/`deliver()` throw `TransformNotReadyError` so a request never stalls behind a remux.
+The split is deliberate.
+Source: `docs/transformers.mdx` (Reads never generate a transform).
+
+### [HIGH] Declaring conversion presets on a non-image collection
+
+Wrong:
+
+```ts
+defineConfig({
+  collections: [
+    { name: 'videos', acceptsMimeTypes: ['video/mp4'], conversions: [{ name: 'thumb', width: 320 }] },
+  ],
+})
+```
+
+Correct:
+
+```ts
+import { defineConfig, transformers } from '@adonis-agora/media'
+
+defineConfig({
+  collections: [
+    {
+      name: 'videos',
+      acceptsMimeTypes: ['video/mp4'],
+      transformers: [transformers.probe({ eager: true })], // non-image derivations
+    },
+  ],
+})
+```
+
+Mechanism: presets decode the original as an image through sharp; requesting one on a video
+or PDF fails inside sharp. Transformers are the seam for everything beyond images and
+persist into the same `record.conversions` namespace (name collisions throw
+`TransformerConflictError` at boot).
+Source: `docs/collections-and-conversions.mdx` (warn callout), `docs/transformers.mdx`.
+
+### [HIGH] Trusting the declared mimeType as the real content type
+
+Wrong:
+
+```ts
+// client renames payload.png → report.pdf and declares 'application/pdf'
+await media.library.attach({
+  ownerType: 'Patient', ownerId: '7', collection: 'exams',
+  fileName: 'scan.pdf', mimeType: 'application/pdf', contents, // bytes are PNG
+})
+```
+
+Correct:
+
+```ts
+try {
+  await media.library.attach({ ownerType: 'Patient', ownerId: '7', collection: 'exams',
+    fileName: 'scan.pdf', mimeType: 'application/pdf', contents })
+} catch (error) {
+  if (error instanceof ContentTypeMismatchError) {
+    // error.declaredMimeType vs error.detectedMimeType — reject with a 4xx
+  }
+  throw error
+}
+```
+
+Mechanism: with `acceptsMimeTypes` present the library reads the file's magic-byte signature
+(first 189 bytes, replayed for streams) and validates the REAL content — a renamed file is a
+`ContentTypeMismatchError` even though the declared type is whitelisted. Only the head is
+read; the payload stays streaming.
+Source: `docs/collections-and-conversions.mdx` (The content is checked too).
+
+See also: `media-attachments-single-file/SKILL.md` — the column-attachment shape for
+single-file fields; `media-uploads-resumable/SKILL.md` — landing large uploads as records
+via `attachExisting`; `media-stores-delivery/SKILL.md` — serving with delivery modes.