@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/media-variants.d.ts

@@ -0,0 +1,309 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * WebP variant generation for a media asset (AGL-175), and the record of
+ * whether it worked (AGL-1468).
+ *
+ * ## Why this is a library function and not two copies of a `try`
+ *
+ * `/api/media/upload` and `/api/media/replace` each carried the same eleven
+ * lines, wrapped in a `catch` whose comment read *"Variants are an
+ * optimization — never fail the upload for them."* That judgement is right and
+ * it survives here. What did not survive is its consequence: the catch wrote
+ * `console.error` and nothing else, so a **total** failure and a **healthy**
+ * asset produced byte-identical documents — `variants: []` either way.
+ *
+ * Measured 2026-08-13 on production: **1 of 180 media documents has a
+ * non-empty `variants` array.** The last successful generation was
+ * 2026-07-19; every image uploaded since has an empty one. Nothing surfaced
+ * that for three weeks, because the only trace was a serverless log line
+ * whose retention is about an hour.
+ *
+ * So the contract of this function is not "generate variants". It is
+ * **generate variants and say what happened**, and the two failure classes
+ * are kept apart on purpose:
+ *
+ * - `variants: []` with **no** `error` — nothing was ELIGIBLE. A type in
+ *   {@link MEDIA_TYPES_WITHOUT_VARIANTS}, a non-image, or a source already
+ *   narrower than every target width. This is the correct, common,
+ *   uninteresting outcome and must never look like a fault or the fault signal
+ *   is worthless.
+ * - `variants: []` with an `error` — generation was attempted and did not
+ *   complete. That string goes onto the media document and bumps a counter,
+ *   which is what makes "how many assets failed?" a query instead of an
+ *   archaeology project.
+ *
+ * A partial run reports both: the widths that landed AND the error, because
+ * the widths that landed are real files that the CDN route can serve.
+ */
+/** The shape of `sharp`'s default export, narrowed to what is used here. */
+type SharpFactory = (input: Buffer) => {
+    resize(options: {
+        width: number;
+        withoutEnlargement: boolean;
+    }): {
+        webp(options: {
+            quality: number;
+        }): {
+            toBuffer(): Promise<Buffer>;
+        };
+    };
+};
+export interface MediaVariantOutcome {
+    /** Widths actually written. Safe to store — every entry is a real object. */
+    variants: number[];
+    /**
+     * Present ONLY when generation was attempted and did not complete.
+     * `undefined` means nothing went wrong, which includes "nothing to do".
+     */
+    error?: string;
+}
+/**
+ * `image/*` types that produce no variants, for two different reasons.
+ *
+ * SVG is a vector: there is nothing to downscale, and rasterizing it would be
+ * a different asset rather than a variant of this one.
+ *
+ * ICO carries no `sharp` decoder at all, so attempting it raises an
+ * unsupported-format error from `toBuffer` — an ERROR on the media document,
+ * which is the signal reserved for generation that was attempted and broke. An
+ * icon having no variants is neither attempted nor broken; it is the ordinary
+ * outcome, and it has to read as one or the fault counter measures the favicon
+ * instead of a fault (AGL-3121).
+ *
+ * Exported because the backfill script has to skip exactly this set. It kept a
+ * second copy of the SVG half, which is how ICO came to be missing from one
+ * and not the other.
+ */
+export declare const MEDIA_TYPES_WITHOUT_VARIANTS: ReadonlySet<string>;
+/**
+ * Which widths this source should produce.
+ *
+ * Split out and exported because it is the predicate that decides whether an
+ * empty result is NORMAL, and both the routes and the health probe have to
+ * agree on it. Inlined, the skip rule was a `continue` buried in the loop that
+ * a reader had to reconstruct in order to know whether `[]` was a bug.
+ *
+ * Widths narrower than the source always; for {@link SOURCE_WIDTH_WEBP_TYPES}
+ * the rest as well, provided the source is wider than the narrowest width — a
+ * source smaller than every candidate is an icon, and it is served as it is.
+ */
+export declare function mediaVariantWidthsFor(options: {
+    contentType: string;
+    /** Source pixel width, when it could be read from the header. */
+    sourceWidth?: number | null;
+}): number[];
+/**
+ * Resolve `sharp`'s callable through either module shape.
+ *
+ * `(await import('sharp')).default` is correct under Node ESM and under a
+ * bundler that synthesises the CJS namespace. It is `undefined` under one that
+ * hands back `module.exports` directly — and `undefined(buffer)` is a
+ * `TypeError` raised INSIDE the same `try` that catches a genuine load
+ * failure, so from outside the two are the same event: no variants, no
+ * message, a 200. This normalises the shape and, when neither shape yields a
+ * function, throws something that NAMES the problem instead of a bare
+ * `is not a function` from three frames away.
+ */
+export declare function loadSharp(): Promise<SharpFactory>;
+/**
+ * A short, PUBLISHABLE name for why the encoder is unavailable (AGL-1471).
+ *
+ * The first thing the probe said on production was `sharp-unavailable`, and
+ * that answered less than it looked like it did: it is the fallback for "the
+ * error carried no `code`", and BOTH interesting failures land there. `sharp`
+ * catches every `require` of its prebuilt binaries and rethrows one composed
+ * `Error` with no `code` at all; `loadSharp` throws a plain `Error` too when
+ * the module resolves to something that is not callable. One means the native
+ * library did not load, the other means the bundler handed back the wrong
+ * shape, and they have nothing in common except the remedy being different.
+ *
+ * Matching on `sharp`'s own help text is the only signal available — the
+ * distinction is not in a field, only in the prose. It is matched loosely and
+ * it degrades to the old fallback, so a reworded upstream message costs a
+ * detail rather than the answer.
+ *
+ * The MESSAGE still never leaves the process. A native loader failure names
+ * every path it tried, the health endpoint is public, and the point of a code
+ * is that it is a fixed vocabulary the caller can branch on.
+ */
+export declare function classifyLoadFailure(error: unknown): string;
+/**
+ * Generate the WebP variants for one asset and report the outcome.
+ *
+ * `saveVariant` is a callback rather than a `Bucket` so this stays free of a
+ * storage dependency and so a spec can assert on the BYTES it produces —
+ * which is the only assertion that distinguishes a working variant from the
+ * original served back under a `?w=` that selects nothing.
+ */
+export declare function generateMediaVariants(options: {
+    buffer: Buffer;
+    contentType: string;
+    sourceWidth?: number | null;
+    /** Object path of the ORIGINAL; variants are `${objectPath}__w{n}.webp`. */
+    objectPath: string;
+    saveVariant: (path: string, webp: Buffer) => Promise<void>;
+}): Promise<MediaVariantOutcome>;
+/**
+ * The largest object this will pull back OUT of storage in order to generate.
+ *
+ * Deliberately equal to `IMAGE_MAX_BYTES`, the console's per-type ceiling for
+ * an image (`apps/console/utils/media-upload-limits.ts`), rather than derived
+ * from it: this library cannot import that file, and the two numbers answer
+ * different questions. That one asks "may this be uploaded at all"; this one
+ * asks "may a serverless function afford to fetch it back and decode it". They
+ * agree today, which is the point — every image the DAM accepts gets variants.
+ * If the upload ceiling is ever raised for a format where 15 MB is small (a
+ * camera RAW, a TIFF), the download stops there instead of silently following
+ * it into a timeout, and says so.
+ */
+export declare const MEDIA_VARIANT_SOURCE_MAX_BYTES: number;
+/**
+ * Generate variants for an object whose bytes are in STORAGE, not in hand
+ * (AGL-1476).
+ *
+ * `/api/media/upload` has the buffer — the client base64'd it into the request
+ * body. `/api/media/upload-url` never sees it: the browser PUTs straight to GCS
+ * with a signed URL, and finalize is handed a path. Since AGL-1465 gave images
+ * a signed-path ceiling, every image between 3 MB and 15 MB takes that route,
+ * so the assets that most need a 320px WebP became precisely the ones that got
+ * none. Measured on production 2026-08-13: a 6,606,921 B PNG landed with
+ * `variants` **absent**, and `?w=320` served back all 6,606,921 B of
+ * `image/png`; a 2,168,376 B PNG on the base64 route landed with
+ * `variants: [320, 640]` and answered `?w=320` in 31,566 B of `image/webp`.
+ *
+ * So the bytes have to come back. `readSource` is a callback, for the same
+ * reason `saveVariant` is one: this stays free of a storage dependency, and a
+ * spec can hand it a real PNG and count what comes out.
+ *
+ * **The read is the last thing that happens, not the first.** Widths are
+ * decided from the header dimensions the caller already has, so a source
+ * narrower than every target width — and every non-image — costs nothing at
+ * all. That ordering is what keeps this from pulling a 200 MB video back out
+ * of the bucket to discover it has no variants.
+ *
+ * The size refusal is reported as an ERROR rather than as an empty success,
+ * and the distinction is AGL-1468's: `variants: []` with no error means
+ * nothing was ELIGIBLE, and an image the platform accepted and then declined
+ * to optimize is not that. It is eligible work that did not happen, so it
+ * belongs on the document and in `variantFailures` where it can be counted.
+ */
+export declare function generateStoredMediaVariants(options: {
+    contentType: string;
+    /** The object's REAL size, as storage reports it. */
+    sizeBytes: number;
+    sourceWidth?: number | null;
+    objectPath: string;
+    /** Fetches the whole object. Only ever called when there is work to do. */
+    readSource: () => Promise<Buffer>;
+    saveVariant: (path: string, webp: Buffer) => Promise<void>;
+    maxSourceBytes?: number;
+}): Promise<MediaVariantOutcome>;
+/**
+ * Can this deployment produce a variant at all?
+ *
+ * Synthesises a small image in memory, downscales it, and asserts the result
+ * is both a WebP and SMALLER than the source. No Storage, no Firestore, no
+ * upload — so it can run from a health endpoint on a schedule instead of
+ * waiting for a customer to notice their thumbnails are full-size originals.
+ *
+ * The size comparison is the point. A resize that silently returns its input
+ * is exactly the failure this issue is about: `?w=640` answering 200 with the
+ * original is indistinguishable from success unless something counts bytes.
+ */
+export declare function probeMediaVariantSupport(): Promise<{
+    ok: boolean;
+    code?: string;
+}>;
+/**
+ * The largest poster this will accept from a client (AGL-2742).
+ *
+ * The browser encodes the still it captured as WebP at quality ~0.72, and a
+ * 1920-wide frame of real video lands between 40 KB and 250 KB. 4 MB is
+ * therefore ~16x the worst realistic case and is not a quality knob: it is
+ * the point past which the bytes stopped being a poster. It has to sit well
+ * under the platform's 4.5 MB request-body wall, because the poster rides
+ * base64 in the finalize call and a ceiling that admits a body the platform
+ * will reject turns a refusal we can explain into a 413 we cannot.
+ */
+export declare const MEDIA_POSTER_MAX_BYTES: number;
+/**
+ * The widest poster stored. Above this a still is being kept at a resolution
+ * no `<video poster>` paints — the element scales it to the player box, and
+ * the largest realistic player box is the 1920 the variant widths already
+ * top out at.
+ */
+export declare const MEDIA_POSTER_MAX_WIDTH = 1920;
+export interface MediaPosterOutcome {
+    /** Set only when a poster object was actually written. */
+    poster?: {
+        width: number;
+        height: number;
+        variants: number[];
+    };
+    /**
+     * Present ONLY when a poster was offered and could not be produced —
+     * the same two-failure-class contract {@link MediaVariantOutcome} keeps.
+     * An upload with no poster offered returns an empty object, not an error.
+     */
+    error?: string;
+}
+/**
+ * Turn a client-supplied still into the asset's poster (AGL-2742).
+ *
+ * ## The re-encode is a security control, not a compression pass
+ *
+ * These bytes come from a browser, over the wire, and land in the shared
+ * media bucket under an org's own prefix, where `serveMediaCdn` will stream
+ * them `inline` from the console's origin and from every tenant site's. That
+ * is precisely the shape of AGL-1474, where an uploaded `image/svg+xml`
+ * turned out to be a scripted document served from `app.aglyn.com`.
+ *
+ * Nothing here trusts the declared type, the magic bytes, or the extension.
+ * The buffer is decoded by `sharp` and **re-encoded** to WebP, so what gets
+ * stored is bytes this process produced. A polyglot, an SVG, an HTML file
+ * with a PNG header — each either fails to decode (reported, no object
+ * written) or becomes a real raster WebP with whatever it was smuggling
+ * discarded. That is a stronger guarantee than any sniffing gate, and it is
+ * why the poster is allowed to be client-generated at all.
+ *
+ * ## Why it reuses `generateMediaVariants` rather than looping itself
+ *
+ * A poster IS an image, and the width set a poster should offer is the width
+ * set every other image offers — the srcSet the renderer already knows how
+ * to write. Handing the generator `{objectPath}__poster` as its object path
+ * makes it emit `{objectPath}__poster__w{n}.webp` with no knowledge that
+ * video exists, and inherits its skip rule, its partial-run reporting and
+ * its refusal to fail an upload. A private loop here would be a second set
+ * of widths to keep in step, which is the defect AGL-175's widths list was
+ * moved into `@aglyn/aglyn` to prevent.
+ *
+ * The dimensions returned are read back from the ENCODED bytes rather than
+ * taken from the caller. The browser's report is what sized the capture, and
+ * the resize below may have changed it; a document that records what was
+ * asked for instead of what was written is how an `aspect-ratio` drifts off
+ * by the cap.
+ */
+export declare function generateMediaPoster(options: {
+    /** Raw bytes as received. Never assumed to be an image of any kind. */
+    buffer: Buffer;
+    /** Object path of the ORIGINAL video, without the poster suffix. */
+    objectPath: string;
+    saveVariant: (path: string, bytes: Buffer) => Promise<void>;
+    maxWidth?: number;
+}): Promise<MediaPosterOutcome>;
+export {};