@tgmc/media-client
Portable media HTTP client (browser + Node) for TGMC portfolio apps.
Package README: packages/media-client/README.md.
Role
Talks to /api/media/* or /api/admin/media/* via path-agnostic baseUrl + Bearer token. Does not import @tgmc/media (Node SDK) or Nuxt.
import { createMediaApiClient } from '@tgmc/media-client';
const { token } = useAdminSession(); // @tgmc/admin's media page
const client = createMediaApiClient({
baseUrl: '/api/admin/media',
getToken: () => token.value,
});
Host differences
| Method | /api/admin/media |
/api/media (@tgmc/media-nuxt) |
|---|---|---|
uploadBase64 |
Yes (POST /assets base64 JSON) |
No — use createPresign → PUT → completeIngest |
materialize |
variant (+ format), recipe, or neither (the t thumbnail) |
Same |
createPresign |
Not used (admin forwards uploads server-side) | { kind, mime, filename, tenant?, byteSize? } → { assetId, path, name, expiresAt, uploadUrl, headers, byteSize? } |
completeIngest |
Via admin remote forward | { assetId, path, … } with optional filename / meta / sha256 / byteSize |
ingestSvg |
Not used (admin forwards uploads server-side) | { filename, svg, tenant?, meta? } → the asset; the only SVG upload (createPresign refuses SVG) |
Pass the file’s byteSize to createPresign and completeIngest: the URL is then signed for exactly that many bytes, and either call answers 413 too_large over the kind’s cap (media-nuxt § Upload size cap). It is optional while unsized uploads are phased out. Calling completeIngest again for an asset that is already registered returns that asset.
completeIngest also takes preSanitized and preSanitizedSig, sent as given. Only the admin server uses them: preSanitizedSig is the HMAC it computes with MEDIA_PRESANITIZE_SECRET for a PDF or MP4 it already sanitized (media-nuxt § Admin preSanitized signature). The secret never reaches a browser.
Types, keys and name conflicts
MediaAsset has tenant, name and path (m/{tenant}/{kind}/{name}.{ext}, the CDN path without the leading slash); MediaChild has variant (t/640/1280/1920/custom) and path. blobKey is gone.
materialize(id, { role?, variant?, format?, recipe?, useDefaultThumb? }): role is a free label that defaults to the variant code. variant: 'p' is reserved and answered with 400.
A 409 from createPresign, completeIngest or uploadBase64 whose body has data.code === 'name_conflict' is thrown as MediaNameConflictError (a MediaApiError) carrying path, suggestedName, suggestedFilename and suggestedPath; show the suggestion and let the user confirm a rename. Other 409s stay a plain MediaApiError. parseNameConflictData(body) is exported for hosts that forward the body (the admin proxy uses it) and returns null for any other body.
In-use refusals. deleteAsset(id) of an asset a published page uses is refused and nothing is deleted: the 409 whose body has data.code === 'in_use' is thrown as MediaInUseError (a MediaApiError, status 409) carrying pages: MediaUsagePage[], every page that uses it ({ pageType, pageId, pageLabel, url, state }, a portable copy of @tgmc/media’s type; state: 'pending' is a publish still being recorded). deleteAsset(id, { force: true }) sends ?force=1 and deletes it anyway; it is admin-only (a tenant token gets a 403 admin_only). The query is sent only when force is set, and the result is { deleted, forced? } (forced is absent from servers that predate the usage list). parseInUseData(body) returns { code: 'in_use', pages }, dropping malformed page entries, or null for any other body (the admin proxy uses it). getAssetUsage(id) reads GET …/assets/:id/usage: { assetId, pages }, pages [] when none. renameAsset answers the asset plus usedBy: the pages whose stored /m/ URLs stopped working (a warning, never a refusal), null when the server could not read them, absent from older servers. On the admin media page an in-use refusal is the message line’s Not deleted: used by 2 published pages: Harbor notes, About. (deleteRefusedMessage in core/admin/app/utils/media-errors.ts, at most three labels, then and <k> more).
Every MediaApiError also carries serverMessage: the statusMessage (else message) of an h3 JSON error body, such as Image edge exceeds max (4096px) on a 422, or null for any other body. parseServerMessage(body) is the exported parser. Show it for client errors (4xx) only; the admin media page does this through mediaFailureMessage(error, fallback) in core/admin/app/utils/media-errors.ts, which keeps 5xx reasons off the page. Browsers still log the failed request (for example “Failed to load resource: 422”) in the console; that is accepted for a rejected request.
Env / auth
Caller supplies Bearer via getToken. Hosts enforce ADMIN_TOKEN.
Requirements: docs/plans/2026-09-22-004-feat-media-host-adapters-plan.md.