@omelhorsite/sdk 0.2.0 → 0.3.0

package/dist/types/resources/linkTrees.d.ts

@@ -10,26 +10,56 @@
  */
 import { Resource } from "../http";
 import type { BaseRecord, FileInput, Id, RequestOptions, Timestamp } from "../types";
-/** Longest a slug may be. The shortest is 2. */
+/**
+ * The reserved short-link namespace a link tree is served under.
+ * `ShortLink::LINK_TREE_NAMESPACE`.
+ *
+ * Note it is `"t"` and not `"lt"`. The model's own comment says `"lt"`; the
+ * constant says `"t"`, and the constant is what the rows carry.
+ */
+export declare const LINK_TREE_NAMESPACE = "t";
+/** Public prefix a link tree resolves under. */
+export declare const LINK_TREE_BASE_URL = "https://omelhor.site/t";
+/** Longest a slug may be. */
 export declare const LINK_TREE_SLUG_MAX_LENGTH = 63;
+/**
+ * Shortest a slug may actually be, which is **3** and not the 2 that
+ * `LinkTree::SLUG_MIN` claims.
+ *
+ * Two validations run, and the tighter one wins. The length check allows 2,
+ * but `SLUG_FORMAT` is `/\A[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])?\z/`: either the
+ * optional group is absent, which matches ONE character and then fails the
+ * length check, or it is present and contributes at least two more. There is
+ * no way to spell a valid two-character slug, so a caller that trusts
+ * `SLUG_MIN` gets a 400 saying the slug "contains invalid characters".
+ */
+export declare const LINK_TREE_SLUG_MIN_LENGTH = 3;
 /** Most items one tree may carry. */
 export declare const LINK_TREE_MAX_ITEMS = 30;
 /** Ceiling on the attached CV, which must also be a PDF. */
 export declare const LINK_TREE_CV_MAX_BYTES: number;
 /**
- * One entry on a link tree.
+ * One entry on a link tree, AS READ back.
  *
- * `url` must carry an `http`, `https`, `mailto`, `tel` or `sms` scheme; a bare
- * domain is rejected by the model, not silently fixed.
+ * `id` is not optional here even though it is optional when writing:
+ * `LinkTrees::InputSanitizer#items` mints `SecureRandom.uuid` for any entry
+ * that arrives without one, so a stored entry always has one - and it has to,
+ * because it is the key `clicks_by_item` is filed under.
+ *
+ * `label` and `url` are likewise always present, because an entry missing
+ * either is DROPPED from the list rather than stored blank. The three
+ * remaining keys are genuinely absent when unset: the sanitiser only writes
+ * `icon` and `description` when non-blank, and `icon_image` only when it is a
+ * `data:image/` URI under the cap.
+ *
+ * Write with {@link LinkTreeItemInput}.
  */
 export interface LinkTreeItem {
-    /** Stable within the tree, and the key click tracking is filed under. The
-     * server mints a UUID when you leave it out, so read the tree back before
-     * calling {@link LinkTreesNamespace.trackClick}. */
-    readonly id?: string;
-    /** Up to 80 characters. */
+    /** Stable within the tree, and the key `clicks_by_item` is filed under. */
+    readonly id: string;
+    /** Up to 80 characters, and never blank. */
     readonly label: string;
-    /** Up to 1024 characters, with a scheme. */
+    /** Up to 1024 characters, and never blank. */
     readonly url: string;
     /** Icon slug the renderer resolves. Up to 40 characters. */
     readonly icon?: string;
@@ -38,6 +68,34 @@ export interface LinkTreeItem {
     /** `data:image/...` under 80 KB, for a custom icon. */
     readonly icon_image?: string;
 }
+/**
+ * One entry as WRITTEN.
+ *
+ * `url` must carry an `http`, `https`, `mailto`, `tel` or `sms` scheme; a bare
+ * domain is rejected by the model, not silently fixed. An entry whose `label`
+ * or `url` is blank is dropped by the sanitiser BEFORE validation, so it
+ * disappears without an error rather than failing the write.
+ *
+ * A {@link LinkTreeItem} read off a tree is assignable here, so the
+ * read-edit-write round trip needs no mapping - and keeping each item's `id`
+ * through that round trip is what keeps `clicks_by_item` lined up with
+ * anything.
+ */
+export interface LinkTreeItemInput {
+    /** Omit and the server mints a UUID, which you then have to read back before
+     * you can call {@link LinkTreesNamespace.trackClick} for this entry. */
+    readonly id?: string;
+    readonly label: string;
+    readonly url: string;
+    readonly icon?: string;
+    readonly description?: string;
+    /**
+     * `data:image/...` under 80 KB. `null` and any other non-conforming value
+     * are DROPPED by the sanitiser rather than rejected, so sending `null` here
+     * clears the icon by omission and answers 200 either way.
+     */
+    readonly icon_image?: string | null;
+}
 /**
  * Styling of a link tree. Colours must be `#RRGGBB` and images must be
  * `data:image/` URIs; anything else in here is dropped in silence on write.
@@ -56,38 +114,60 @@ export interface LinkTreeTheme {
     /** `data:image/...` under 1 MB, or `null` to clear. */
     readonly banner_image?: string | null;
 }
-/** A link-in-bio page, owner view. */
+/**
+ * A link-in-bio page, owner view.
+ *
+ * Every key is present on every owner-facing response: index, show, create,
+ * update, `uploadCv` and `removeCv` all render the blueprint's DEFAULT view,
+ * never `:extended`, so there is no richer variant and nothing here is
+ * conditional. Four of the values are nullable.
+ */
 export interface LinkTree extends BaseRecord {
     readonly user_id: Id;
     /** Public path segment. Lowercase letters, digits and dashes. */
     readonly slug: string;
+    /** Never blank: the model validates presence. Up to 80 characters. */
     readonly title: string;
-    readonly bio?: string | null;
-    /** The avatar, inline as a `data:image/` URI rather than a URL. */
-    readonly avatar_data_url?: string | null;
+    /** Up to 280 characters, or `null`. Never `undefined`. */
+    readonly bio: string | null;
+    /** The avatar, inline as a `data:image/` URI rather than a URL, or `null`. */
+    readonly avatar_data_url: string | null;
+    /** Never `null`: the blueprint substitutes `[]` for an unset list. */
     readonly items: LinkTreeItem[];
+    /** Never `null`: the blueprint substitutes `{}` for an unset bag. */
     readonly theme: LinkTreeTheme;
-    /** Click counters keyed by {@link LinkTreeItem.id}. */
+    /**
+     * Click counters keyed by {@link LinkTreeItem.id}. Never `null` - `{}` for a
+     * tree nobody has clicked - and it can hold ids of items that have since
+     * been deleted, because nothing prunes it.
+     */
     readonly clicks_by_item: Record<string, number>;
     /** Absolute URL that downloads the CV, or `null` when none is attached. */
     readonly cv_url: string | null;
     readonly cv_filename: string | null;
-    /** The shareable short URL. */
+    /** The shareable short URL: `{@link LINK_TREE_BASE_URL}/{slug}`. */
     readonly public_url: string;
     /** Endpoint of the paired short link. Always equal to `slug`. */
     readonly short_link_endpoint: string;
-    readonly short_link_namespace: string;
+    /** Always {@link LINK_TREE_NAMESPACE}; the blueprint renders the constant. */
+    readonly short_link_namespace: typeof LINK_TREE_NAMESPACE;
 }
 /**
- * The visitor's view: the same page with the owner-only fields removed. Note
- * that it carries no timestamps, so it is NOT a {@link LinkTree}.
+ * The visitor's view: the same page with the owner-only fields removed.
+ *
+ * The `:public` view excludes exactly seven keys - `user_id`,
+ * `clicks_by_item`, `public_url`, `short_link_endpoint`,
+ * `short_link_namespace`, `created_at` and `updated_at` - and INHERITS
+ * everything else from the default view, which is why `id`, `cv_url` and
+ * `cv_filename` are still here. It carries no timestamps, so it is NOT a
+ * {@link LinkTree} and cannot be passed where one is expected.
  */
 export interface PublicLinkTree {
     readonly id: Id;
     readonly slug: string;
     readonly title: string;
-    readonly bio?: string | null;
-    readonly avatar_data_url?: string | null;
+    readonly bio: string | null;
+    readonly avatar_data_url: string | null;
     readonly items: LinkTreeItem[];
     readonly theme: LinkTreeTheme;
     readonly cv_url: string | null;
@@ -96,18 +176,27 @@ export interface PublicLinkTree {
 /** Arguments for creating a link tree. */
 export interface CreateLinkTreeInput {
     /**
-     * 2 to {@link LINK_TREE_SLUG_MAX_LENGTH} characters of `[a-z0-9-]`, starting
-     * and ending alphanumeric, and never one of `new edit admin api root login
-     * logout signup signin manage`.
+     * {@link LINK_TREE_SLUG_MIN_LENGTH} to {@link LINK_TREE_SLUG_MAX_LENGTH}
+     * characters of `[a-z0-9-]`, starting and ending alphanumeric, and never one
+     * of `new edit admin api root login logout signup signin manage`.
+     *
+     * Lowercased and trimmed server-side before any check, so casing is not a
+     * reason to be refused.
      */
     readonly slug: string;
     /** Required: the model refuses a blank title. Up to 80 characters. */
     readonly title: string;
     /** Up to 280 characters. */
     readonly bio?: string;
-    /** `data:image/...` under 500 KB. Build one with `dataUrlFromFile`. */
+    /**
+     * `data:image/...` under 500 KB. Anything else - a plain URL, an oversized
+     * image - is turned into `null` by the sanitiser before validation, so a bad
+     * avatar creates the tree WITHOUT one rather than failing. Read
+     * `avatar_data_url` back off the answer.
+     */
     readonly avatarDataUrl?: string;
-    readonly items?: LinkTreeItem[];
+    /** At most {@link LINK_TREE_MAX_ITEMS}; more is a 400. */
+    readonly items?: LinkTreeItemInput[];
     readonly theme?: LinkTreeTheme;
 }
 /**
@@ -123,9 +212,16 @@ export interface UpdateLinkTreeInput {
     /** Renames the paired short link; the old public URL stops resolving. */
     readonly slug?: string;
     readonly title?: string;
-    readonly bio?: string;
+    /**
+     * Accepts `null`, but note what it does: the controller assigns
+     * `params[:bio].to_s.strip`, so `null` stores the empty STRING and not
+     * `null`. There is no way through this endpoint to put the column back to
+     * `null` once it holds a value; `""` is as empty as it gets.
+     */
+    readonly bio?: string | null;
+    /** `null` or `""` clears the avatar. Anything malformed also clears it. */
     readonly avatarDataUrl?: string | null;
-    readonly items?: LinkTreeItem[];
+    readonly items?: LinkTreeItemInput[];
     readonly theme?: LinkTreeTheme;
 }
 /** One day of the click histogram. Always 30 entries, oldest first. */
@@ -171,8 +267,14 @@ export interface LinkTreeSlugAvailability {
     readonly slug: string;
     readonly valid: boolean;
     readonly available: boolean;
-    /** `"invalid"` for the format, `"reserved"` for the blocklist. */
-    readonly reason?: string;
+    /**
+     * Only when `valid` is `false`. `"invalid"` for the format or the length,
+     * `"reserved"` for the blocklist - link trees distinguish the two, unlike
+     * the otherwise identical `FormEndpointAvailability`, which only ever says
+     * `"invalid"`.
+     */
+    readonly reason?: "invalid" | "reserved";
+    /** Only when `valid` is `true` and `available` is `false`. */
     readonly suggestions?: string[];
 }
 /** The `linkTrees` namespace, reachable as `oms.linkTrees`. */
@@ -246,4 +348,14 @@ export declare class LinkTreesNamespace extends Resource {
      * which slugs exist.
      */
     trackClick(slug: string, itemId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * The public URL a slug is served from. Pure string building, no request, and
+     * the same string the server puts in {@link LinkTree.public_url}.
+     *
+     * Prefer `tree.public_url` when you are holding an owner-view record. Reach
+     * for this when all you have is a slug - after {@link slugAvailability}, or
+     * from a {@link PublicLinkTree}, whose `:public` view deliberately drops
+     * `public_url` along with the rest of the pairing metadata.
+     */
+    publicUrl(slug: string): string;
 }

package/dist/types/resources/media.d.ts

@@ -0,0 +1,351 @@
+/**
+ * The `media` namespace: the canonical bytes of the music library.
+ *
+ * A song, an artist and a playlist never carry bytes or URLs inline. They carry
+ * MEDIA IDS - `audio_media_id`, `compressed_artwork_media_id`,
+ * `image_media_id`, `vocals_media_id` and the rest - and this namespace is the
+ * one place those ids turn into something playable.
+ *
+ * ## Two routes, and which one is the real one
+ *
+ * - `GET /media/:id/data` and `GET /media/:id/data_url` are the CANONICAL
+ *   routes. `MediaController` serves them, and every new client should use
+ *   them.
+ * - `GET /fs_nodes/:id/data` and `GET /fs_nodes/:id/data_url` are a TEMPORARY
+ *   ALIAS, in the backend's own words: "the old `/fs_nodes/:id/data{,_url}`
+ *   routes keep a temporary numeric-id alias for the web frontend".
+ *   `FsNodesController` branches on `params[:id] =~ /\A\d+\z/` and hands a
+ *   numeric id to the same `MusicMediaServing` concern; a storage UUID keeps
+ *   the old filesystem behaviour. The alias exists because the web frontend
+ *   still builds those URLs, and it is scheduled to go together with the
+ *   `*_fs_node_id` blueprint twins.
+ *
+ * {@link MediaNamespace.aliasUrl} and {@link MediaNamespace.aliasDataUrl} are
+ * here so a port of the old web code type-checks, and for the one case where
+ * the alias is genuinely more capable (see the OAuth note below). Reach for
+ * {@link MediaNamespace.url} and {@link MediaNamespace.dataUrl} in new code.
+ *
+ * ## A media id is not a storage node id
+ *
+ * It is an `active_storage_attachments` primary key, which
+ * `ApplicationBlueprint.media_id_fields` serialises with `.to_s` - so it is a
+ * STRING whose characters happen to all be digits (`"48211"`). Storage node
+ * ids are uuids. The two id spaces are not interchangeable, and the only
+ * reason a media id works on the `fs_nodes` path at all is the numeric branch
+ * described above. {@link isMediaId} exists to keep that straight.
+ *
+ * ## 404 NEVER 401, and why that will empty somebody's library
+ *
+ * `resolve_music_attachment` returns `nil` - and the controller answers `404
+ * "Not found"` - for every one of these, deliberately indistinguishable:
+ *
+ * - the id does not exist;
+ * - it exists but belongs to a book, a tool output, another user;
+ * - the caller sent no credential at all;
+ * - the caller sent a credential that no longer resolves to a live session.
+ *
+ * The routes are declared `allow_unauthenticated_access`, so authentication
+ * never gets a chance to answer `401`. That is correct for the server:
+ * existence must not leak. It is a TRAP for the client.
+ *
+ * A client that reads `404` as "this file is gone" will, the moment a session
+ * expires or a token rotates, quietly render an entire library of broken
+ * artwork and unplayable tracks - and it will look like data loss, not like a
+ * sign-in problem, because nothing anywhere returned `401`. **Never conclude
+ * "missing" from a media 404 alone.** Confirm the session first with a route
+ * that does distinguish the two (`oms.account.me()` answers `401` when the
+ * credential is dead) and only then decide the media is really gone.
+ * {@link isMediaMissing} carries that warning at the point of use.
+ *
+ * ## The rate ceilings are not the same on the two routes, and that is the point
+ *
+ * `rack-attack`'s `GENERAL_EXEMPT_PATHS` matches `/media/:id/data` and
+ * `/fs_nodes/:id/(data|zip)`, and matches NEITHER `data_url`:
+ *
+ * - **`data` is EXEMPT** from the 600/min authenticated and 120/min anonymous
+ *   ceilings, on both the canonical route and the alias. An artwork grid, a
+ *   prefetch sweep and a bulk download can hammer it without spending the
+ *   account's budget. This is the route for images and for downloads.
+ * - **`data_url` COUNTS** against the general ceiling like any other call.
+ *   Resolving a presigned URL per tile in a scrolling grid is how a client
+ *   429s itself out of the whole API. Reserve it for the player's resolver,
+ *   which needs a URL a media element can load cross-origin, and cache what it
+ *   returns BY MEDIA ID - never by URL, because a fresh signature comes back
+ *   on every single resolve.
+ *
+ * The exemption is matched against a normalised path with the format suffix
+ * stripped, so `/media/48211/data.json` is exempt too, and a query string
+ * never changes the verdict.
+ *
+ * ## An OAuth access token cannot reach `/media/*` at all
+ *
+ * `MediaController` declares no `oauth_scope`, and `enforce_oauth_scope!`
+ * denies by omission: an OAuth token gets `403 {"error":"insufficient_scope"}`
+ * before the action runs. `FsNodesController` DOES declare `storage:read` on
+ * `data`/`data_url`, so - until `MediaController` grows a scope - a token
+ * holding `storage:read` can reach music bytes through the temporary alias and
+ * not through the canonical route. That inversion is a server-side gap rather
+ * than a design decision; it is the single reason to prefer the alias, and it
+ * is expected to close. A session token or the browser cookie reaches both.
+ *
+ * ## Who may read what
+ *
+ * Owner-only, with exactly one hole cut in it on purpose: the `audio`,
+ * `compressed_audio`, `artwork` and `compressed_artwork` attachments of a SONG
+ * that sits, unhidden, in a `friends`-visibility playlist belonging to one of
+ * the caller's friends. Stems, artist images and playlist covers stay
+ * owner-only. Every other cross-user surface in the API - jams, the friends
+ * feed, music profiles - ships READY-MADE presigned `artwork_url` / `audio_url`
+ * strings instead; use those verbatim and never try to re-derive one from an id
+ * you do not own, because that is a 404.
+ */
+import { Resource } from "../http";
+import type { FileOutput, RequestOptions } from "../types";
+/**
+ * An `active_storage_attachments` id, as the blueprints serialise it: a string
+ * of digits.
+ *
+ * Typed as a plain `string` rather than a branded type because that is what
+ * every `*_media_id` field on a song, an artist and a playlist already is, and
+ * a brand would force a cast at every one of them.
+ */
+export type MediaId = string;
+/**
+ * How long a presigned URL from {@link MediaNamespace.dataUrl} stays valid:
+ * six hours (`MediaUrls::EXPIRY`).
+ *
+ * The window is long because it has to be, not out of generosity. A media
+ * element re-requests the object on every seek and whenever it resumes a
+ * buffered track, so the signing default of five minutes dies mid-listen with
+ * no way to recover. Six hours is also what the cross-user presigned URLs on
+ * jams and the friends feed are signed for.
+ */
+export declare const MEDIA_URL_TTL_MS: number;
+/**
+ * How long a browser may reuse the `302` from `GET /media/:id/data`:
+ * five minutes (`MusicMediaServing::REDIRECT_CACHE_TTL`), `Cache-Control:
+ * private`.
+ *
+ * It exists because a redirect with no `Cache-Control` is never cached, so
+ * every `<img>` re-followed the hop on every mount and artwork visibly
+ * re-fetched itself. Deliberately far below {@link MEDIA_URL_TTL_MS} so a
+ * cached redirect always points at a signature with hours of life left.
+ *
+ * `private` means per-browser: a shared cache must not hold it, because the
+ * response is the product of the caller's own credential.
+ */
+export declare const MEDIA_REDIRECT_CACHE_TTL_MS: number;
+/** The `media` namespace, reachable as `oms.media`. */
+export declare class MediaNamespace extends Resource {
+    /**
+     * Absolute URL of `GET /media/:id/data`, carrying NO credential.
+     *
+     * Synchronous, because it is called while a component renders and a token
+     * provider may be async. What that means depends on the client:
+     *
+     * - **browser, cookie mode**: this is the URL you want. The `oms_session`
+     *   cookie rides along on its own, the element follows the `302` to object
+     *   storage with no CORS check at all, and the redirect is cacheable for
+     *   {@link MEDIA_REDIRECT_CACHE_TTL_MS}. Do NOT put `crossorigin` on the
+     *   element: it turns a no-cors load into a CORS one and re-creates exactly
+     *   the failure the split between `data` and `data_url` exists to avoid.
+     * - **token mode (the native app, the CLI)**: this URL alone is a `404`,
+     *   because no credential reaches the server. Use
+     *   {@link authenticatedUrl} instead.
+     *
+     * Rate-limit exempt (see the namespace notes), which is what makes it the
+     * right route for an artwork grid and for a prefetch sweep.
+     */
+    url(id: MediaId): string;
+    /**
+     * {@link url} with the caller's token appended as `?token=`, for an `<img>`,
+     * an `<audio>`, a lock-screen artwork slot or a native downloader - anything
+     * that fetches a URL itself and cannot be given an `Authorization` header.
+     *
+     * Asynchronous because resolving the credential may refresh it, so it cannot
+     * be a getter. In cookie mode there is no token and it returns the bare URL,
+     * which is the correct answer there.
+     *
+     * `Session.candidate_tokens` reads the `Authorization` header, then
+     * `params[:token]`, then the cookie, so a query token is a first-class
+     * credential on this route - and, unlike on the HTML pages served by this
+     * host, it is not a redirect-injection risk here because there is no page to
+     * render as somebody else.
+     *
+     * **THE RESULT IS A LIVE CREDENTIAL.** It goes into the DOM, into the server
+     * access log, into `Referer` and into anything that records URLs; anyone
+     * holding it holds the whole session until it is revoked. Build it at the
+     * moment of use, never store it, never log it, and never hand it to
+     * something outside your own app - fetch the bytes with {@link download} and
+     * pass a `blob:` URL instead.
+     *
+     * One consequence worth planning for: the token is part of the URL, so it is
+     * part of the browser HTTP cache key. Every sign-in invalidates the warmed
+     * artwork cache of a token-mode client. That costs one cold cache, never
+     * correctness, and there is no client-side fix.
+     *
+     * ```ts
+     * const src = await oms.media.authenticatedUrl(song.compressed_artwork_media_id);
+     * ```
+     */
+    authenticatedUrl(id: MediaId): Promise<string>;
+    /**
+     * `GET /media/:id/data_url` - the presigned object-store URL for these bytes,
+     * as JSON.
+     *
+     * This is the route a PLAYER wants. `data` answers a `302` to storage, and a
+     * cross-origin media request cannot survive that hop either way: sent with
+     * credentials the browser turns `Origin` into `null` after the redirect and
+     * the store's wildcard `Access-Control-Allow-Origin` is illegal for a
+     * credentialed request; sent without credentials the route 404s before it
+     * ever redirects. Splitting it in two removes the redirect from the media
+     * request entirely - this call carries the session and returns a URL, and
+     * the element then loads that URL from storage directly and anonymously.
+     *
+     * Three properties that decide how you cache it:
+     *
+     * - **it is DIFFERENT on every call.** A fresh signature per resolve. Cache
+     *   by media id, never by URL, or a cache keyed on the string will miss
+     *   every time and grow forever.
+     * - **it is good for {@link MEDIA_URL_TTL_MS}** (six hours) and then it is
+     *   not. Re-resolve on a playback failure rather than treating one as fatal.
+     * - **it COUNTS against the 600/min authenticated ceiling**, unlike
+     *   {@link url}. One resolve per track as it is about to play is the
+     *   intended shape; one resolve per tile in a grid is not.
+     *
+     * Do not forward your own `Authorization` header when fetching the returned
+     * URL - the signature is the credential, and the object store rejects a
+     * request that carries both.
+     *
+     * @throws {OmsApiError} 404 `"Not found"` - which does NOT mean the media is
+     *   gone. See {@link isMediaMissing} and the namespace notes.
+     * @throws {OmsAuthError} 403 `insufficient_scope` when the client
+     *   authenticated with an OAuth access token; `MediaController` declares no
+     *   scope, so no token reaches it.
+     */
+    dataUrl(id: MediaId, options?: RequestOptions): Promise<string>;
+    /**
+     * `GET /media/:id/data`, following the redirect and reading the bytes into
+     * memory.
+     *
+     * For Bun, a Worker and React Native, where nothing enforces CORS. In a
+     * BROWSER this cannot work and no amount of client code fixes it - the `302`
+     * goes to a different origin, and the two failure modes described on
+     * {@link dataUrl} apply here too. There, put {@link url} or
+     * {@link authenticatedUrl} in an element, or resolve with {@link dataUrl}
+     * and fetch that.
+     *
+     * Buffers everything. A lossless album track is a bad thing to pull through
+     * JavaScript on a phone: resolve a URL and hand it to the platform player or
+     * to a native downloader instead, both of which stream to disk. This method
+     * is for artwork and for the odd file a host really does need in memory.
+     *
+     * The server falls back to sending the bytes inline (with a
+     * `Content-Disposition` filename) when the storage service has no URL host,
+     * which is what dev and test look like; both shapes arrive here identically.
+     *
+     * The runtime follows the redirect, and every conformant one drops the
+     * `Authorization` header on the cross-origin hop. That is not a limitation to
+     * work around: the signature in the presigned URL is the credential, and the
+     * object store rejects a request that arrives carrying both. A hand-rolled
+     * downloader that helpfully re-attaches the header will get a `400` from
+     * storage on bytes the server was perfectly willing to hand over.
+     *
+     * @throws {OmsError} `unsupported` when the redirect was blocked, which in
+     *   practice means a browser in cookie mode.
+     * @throws {OmsApiError} 404 - see {@link isMediaMissing} before believing it.
+     */
+    download(id: MediaId, options?: RequestOptions): Promise<FileOutput>;
+    /**
+     * `GET /fs_nodes/:id/data` - the TEMPORARY numeric-id alias for {@link url}.
+     *
+     * Identical bytes, identical owner-or-404 rule, identical rate-limit
+     * exemption, resolved by the same `MusicMediaServing` concern. It is here for
+     * two reasons and no others: code ported from the old web frontend still
+     * spells it this way, and it is currently the only media route an OAuth token
+     * carrying `storage:read` can reach (see the namespace notes).
+     *
+     * The id must be all digits. `FsNodesController#data` only takes the media
+     * branch for `/\A\d+\z/`; anything else is looked up as a storage node,
+     * which for a media id means a 404 with a completely different cause.
+     * {@link isMediaId} checks that before you spend a request finding out.
+     *
+     * @deprecated Prefer {@link url}. The backend calls this alias temporary and
+     *   it will be removed together with the `*_fs_node_id` blueprint twins.
+     */
+    aliasUrl(id: MediaId): string;
+    /**
+     * `GET /fs_nodes/:id/data_url` - the TEMPORARY numeric-id alias for
+     * {@link dataUrl}, with every caveat that method carries.
+     *
+     * Counts against the rate ceiling exactly as the canonical route does: the
+     * exemption covers `/fs_nodes/:id/data` and `/fs_nodes/:id/zip`, and stops
+     * there.
+     *
+     * Note the asymmetry with {@link aliasUrl}: a NON-numeric id here is not an
+     * error but a different endpoint - the storage node's own data URL - which is
+     * a perfectly valid thing to want and is what `oms.storage.downloadUrl` is
+     * for. Do not use this method to reach a storage node; use that one.
+     *
+     * @deprecated Prefer {@link dataUrl}.
+     */
+    aliasDataUrl(id: MediaId, options?: RequestOptions): Promise<string>;
+}
+/**
+ * Whether a value has the shape the `/fs_nodes` alias routes to media: one or
+ * more digits and nothing else.
+ *
+ * Worth having because the alias branches on exactly this regex. Hand it a
+ * storage uuid and it does not fail loudly - it quietly serves a different
+ * resource, or 404s for a reason that has nothing to do with the media you
+ * asked for.
+ */
+export declare function isMediaId(value: unknown): value is MediaId;
+/**
+ * Whether an error is a media `404`.
+ *
+ * **Read the name as "the server would not serve this", never as "this does
+ * not exist".** The media routes are `allow_unauthenticated_access` and
+ * `resolve_music_attachment` collapses five different situations into the same
+ * `404`, on purpose, so that the existence of a file never leaks: unknown id,
+ * wrong owner, non-music attachment, no credential, and a credential that has
+ * expired.
+ *
+ * The last two are the dangerous ones. A client that deletes its cached row,
+ * or renders a permanent placeholder, on the strength of this returning `true`
+ * will erase a user's entire visible library the first time their session
+ * lapses - with no `401` anywhere to explain it.
+ *
+ * The safe shape:
+ *
+ * ```ts
+ * try {
+ *   src = await oms.media.dataUrl(song.compressed_audio_media_id);
+ * } catch (error) {
+ *   if (!isMediaMissing(error)) throw error;
+ *   // 404 is ambiguous. Ask something that CAN answer 401 before believing it.
+ *   await oms.account.me(); // throws OmsAuthError 401 on a dead session
+ *   markArtworkUnavailable(song); // only now is "gone" a fair conclusion
+ * }
+ * ```
+ */
+export declare function isMediaMissing(error: unknown): boolean;
+/**
+ * The first media id in the list that is actually present, or `null`.
+ *
+ * Every music record offers the same choice twice over: a compressed twin and
+ * an original, either of which may be `null`. The compressed one is what a
+ * client should reach for - the originals are lossless files on a Raspberry Pi
+ * and an album grid that asks for them takes seconds per tile - and the
+ * fallback chain is written out by hand in every client today.
+ *
+ * ```ts
+ * const artwork = firstMediaId(song.compressed_artwork_media_id, song.artwork_media_id);
+ * const audio = firstMediaId(song.compressed_audio_media_id, song.audio_media_id);
+ * ```
+ *
+ * Empty strings are treated as absent: a blueprint field is `null` when there
+ * is no attachment, but a form round-trip through a URL or a database can turn
+ * that into `""`, and an empty id would build a request for `/media//data`.
+ */
+export declare function firstMediaId(...ids: readonly (MediaId | null | undefined)[]): MediaId | null;