@nitida/asset-client 0.14.3 → 0.16.0

package/src/index.ts

@@ -154,11 +154,18 @@ export type AssetDTO = {
   /** Soft-delete timestamp (ISO). Hidden from catalog when set. */
   deletedAt?: string | null;
   /**
-   * Full variant list with URLs + sizes. Present on admin responses
-   * (`GET /assets/:id`); absent on the slim list shape used by the
-   * resolver / catalog. Use `presets` for compact existence checks.
+   * Full variant list with URLs + sizes. Sent by `GET /assets/:id`; absent on
+   * the slim list shape used by the resolver / catalog. Use `presets` for
+   * compact existence checks, and this when you need the actual URLs.
    */
   variants?: AssetVariant[];
+  /**
+   * The extension the `original` variant was really stored under — the server
+   * keys it off the uploaded filename, so it cannot be derived from `mime`.
+   * Sent by `GET /assets/:id`; `null` when the asset has no original.
+   * {@link getAssetUrl} uses it automatically when you pass the whole DTO.
+   */
+  oext?: string | null;
 };
 
 export type {
@@ -201,7 +208,7 @@ export function getCdnBase(): string {
 // `<cdn>/<tenantId base36>/v/<sha16>-<preset>.<ext>` (see asset-manager
 // `variantKey`). Variant URL builders MUST include that prefix or every
 // URL 404s. The tenant id is process-global (one tenant per client/app),
-// set once at boot — `AquienpzClient` does this from its `tenantId` option;
+// set once at boot — `NitidaClient` does this from its `tenantId` option;
 // standalone consumers call `setTenantId()` directly. Left unset, builders
 // fall back to the legacy pre-cutover bare path for back-compat.
 // ---------------------------------------------------------------------------
@@ -225,17 +232,27 @@ function variantPrefix(): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Extension for the ORIGINAL variant, derived from the asset's mime — the
- * original is stored under its real extension (keyed via `extOfMime`), so the
- * static `PRESET_EXT.original` sentinel ("bin") only applies when the mime is
- * unknown/absent. Mirrors the asset-manager's `extOfMime` (mime-types) for the
- * common image/video kinds so the built URL matches the stored R2 key —
- * otherwise original-only uploads build a `-o.bin` URL that 404s while the asset
- * is served at e.g. `-o.png`.
+ * LAST-RESORT guess at the ORIGINAL variant's extension, from the asset's mime.
+ *
+ * ⚠️ This is a guess. Prefer `oext` or `variants` (see {@link getAssetUrl}) — the
+ * server sends both and they ARE the key.
+ *
+ * The server derives the extension from the MIME with the `mime-types` package
+ * (`mime.extension(body.mime)`, at presign). So a table that matched that one
+ * exactly would usually be right — and this table did not: it said
+ * `image/jpeg` → `jpeg` while `mime-types` says `jpg`, under a comment claiming
+ * to mirror it. Usually, but not always: the row's stored `mime` is not always
+ * the mime the key was built from, so no client-side table can close the gap.
+ *
+ * Measured against the 2 001 stored originals in production, 2026-08-17: **all
+ * 420 `image/jpeg` originals are stored `.jpg` and none `.jpeg`** — the old
+ * entry here 404'd on every single JPEG. And 234 originals carry
+ * `application/octet-stream` (`.mpga`, `.docx`, `.m4a`), where no mime table can
+ * produce the right key at all — those need `oext`.
  */
 const ORIGINAL_EXT_BY_MIME: Record<string, string> = {
   "image/png": "png",
-  "image/jpeg": "jpeg",
+  "image/jpeg": "jpg",
   "image/webp": "webp",
   "image/gif": "gif",
   "image/avif": "avif",
@@ -248,19 +265,45 @@ const ORIGINAL_EXT_BY_MIME: Record<string, string> = {
   "video/mp4": "mp4",
   "video/webm": "webm",
   "video/quicktime": "mov",
+  // Audio — ausentes hasta 2026-08-17, y su ausencia costó un rodeo entero en
+  // neo (`withRealOriginalExt`), que existe SÓLO porque esta tabla devolvía el
+  // centinela `bin` para toda nota de voz. Medido en producción: `-o.bin` da
+  // 404 y `-o.m4a` da 200.
+  //
+  // ⚠️ Se keyean por el mime COMPLETO, no por el subtipo: `audio/mp4` guarda
+  // `.m4a` y `video/mp4` guarda `.mp4`. Un `switch` sobre el subtipo `mp4` no
+  // puede distinguirlos — es el error que un consumidor cometió y tuvo que
+  // corregir por su cuenta.
+  "audio/mpeg": "mpga",
+  "audio/mp4": "m4a",
+  "audio/x-m4a": "m4a",
+  "audio/wav": "wav",
+  "audio/webm": "weba",
+  "audio/ogg": "oga",
+  "audio/aac": "adts",
 };
 function originalExtForMime(mime: string | undefined): string {
   return (mime ? ORIGINAL_EXT_BY_MIME[mime] : undefined) ?? PRESET_EXT.original;
 }
 
+/** What the asset itself knows about where its `original` lives. */
+type OriginalHints = {
+  mime?: string;
+  /** The extension the server actually stored it under. Authoritative. */
+  oext?: string | null;
+  /** Full variant list — carries the stored URL verbatim. Authoritative. */
+  variants?: AssetVariant[];
+};
+
 /**
  * Build the public CDN URL for a specific variant of an asset. The variant
  * may not actually exist (regenerate may not have run, or video has no
  * `aiproxy`); call `hasPreset()` first or expect a 404.
  *
- * Pass the asset's `mime` (present on the full `AssetDTO`) so the `original`
- * preset resolves to the correct extension; without it the original falls back
- * to the `"bin"` sentinel.
+ * For the `original` preset, pass the whole `AssetDTO` — it carries `variants`
+ * and `oext`, either of which gives the EXACT stored key. `mime` alone is only a
+ * guess (the server keys the original off the uploaded filename), and with
+ * nothing at all the original falls back to the `"bin"` sentinel, which 404s.
  *
  * @example Video — the tenant segment is base36, so let this build the path
  * ```ts
@@ -271,15 +314,13 @@ function originalExtForMime(mime: string | undefined): string {
  * getAssetUrl({ sha }, "poster");         // → https://8ok.uk/c/v/<sha16>-p.webp
  * ```
  *
- * @example The `original`, which needs the mime — and still deserves a HEAD
+ * @example The `original` — pass the DTO, not just the sha
  * ```ts
- * getAssetUrl({ sha }, "original");             // → …-o.bin   ❌ 404, always
- * getAssetUrl({ sha, mime }, "original");       // → …-o.webp  ✓
+ * const asset = await aq.assets.get(id);
  *
- * // ⚠️ The stored extension comes from the UPLOADED FILENAME, not the mime:
- * // "image/jpeg" builds "-o.jpeg" while a camera's ".jpg" was stored as "-o.jpg".
- * // When the URL must be right, verify it:
- * const res = await fetch(url, { method: "HEAD" });
+ * getAssetUrl({ sha }, "original");        // → …-o.bin   ❌ 404, always
+ * getAssetUrl({ sha, mime }, "original");  // → a guess from the mime table
+ * getAssetUrl(asset, "original");          // ✓ the stored key, verbatim
  * ```
  *
  * @example Check before you link
@@ -289,20 +330,27 @@ function originalExtForMime(mime: string | undefined): string {
  * ```
  */
 export function getAssetUrl(
-  asset: Pick<AssetDTO, "sha"> & { mime?: string },
+  asset: Pick<AssetDTO, "sha"> & OriginalHints,
   preset: VariantPreset,
 ): string {
-  const ext =
-    preset === "original" ? originalExtForMime(asset.mime) : PRESET_EXT[preset];
-  return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT[preset]}.${ext}`;
+  if (preset === "original") {
+    // The stored URL beats every derivation, because it IS the key. Only fall
+    // through to a guess when the caller gave us the sha and nothing else.
+    const stored = asset.variants?.find((v) => v.preset === "original")?.url;
+    if (stored) return stored;
+    const ext = asset.oext || originalExtForMime(asset.mime);
+    return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT.original}.${ext}`;
+  }
+  return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT[preset]}.${PRESET_EXT[preset]}`;
 }
 
 /**
  * Did the processor actually generate this preset?
  *
- * Reads `dto.presets` — the compact 1-char code string the server always sends. Prefer this over
- * the `variants` array, which is documented as present on admin responses and, measured
- * 2026-08-15, comes back EMPTY even with an admin key while the database row holds the variants.
+ * Reads `dto.presets` — the compact 1-char code string the server sends on EVERY shape, including
+ * the slim list/resolver one that carries no `variants` at all. That is why this exists and why it
+ * stays the right existence check even now that `GET /assets/:id` really does send `variants`
+ * (it did not until 2026-08-17; doc 240 §4.3).
  *
  * @example
  * ```ts
@@ -317,11 +365,40 @@ export function hasPreset(
   asset: Pick<AssetDTO, "presets">,
   preset: VariantPreset,
 ): boolean {
-  // `presets` concatenates 1-char short codes, but the audio `mp3` variant is a
-  // literal 3-char token. Query `mp3` against that token; for every other preset
-  // strip `mp3` first so its `m`/`p` can't substring-false-match `md`/`poster`.
   if (preset === "mp3") return asset.presets.includes("mp3");
-  return asset.presets.replace(/mp3/g, "").includes(PRESET_SHORT[preset]);
+  return stripMultiCharTokens(asset.presets).includes(PRESET_SHORT[preset]);
+}
+
+/**
+ * Remove every MULTI-character token from a `presets` string, leaving only the
+ * 1-char codes that a `.includes` can safely be run against.
+ *
+ * `presets` is documented as a concatenation of 1-char codes, and membership is
+ * a 1-char substring test — so any longer token is a false-positive generator.
+ * Servers before the 2026-08-17 deploy emitted several (doc 240 §4.3b):
+ *
+ * | token in the string | letters it donates | presets it falsely answers |
+ * |---|---|---|
+ * | `transform-<hex>` | t r a n s f o m + a–f | `sm` `md` `original` `aiproxy` |
+ * | `pr` (probe) | p r | `poster` |
+ * | `mp3` (audio) | m p | `md` `poster` — stripped here since forever |
+ *
+ * Measured against production: **62 % of live assets** carried a polluted
+ * string, and **16 299 of them were told they have an `original` they do not**
+ * — which builds a `-o.<ext>` URL that 404s. (`aiproxy`: 16 479. `sm`/`md`: 487.
+ * The `pr` → `poster` collision is real but has 0 instances today.)
+ *
+ * Current servers no longer emit these, but this stays: an older
+ * `asset-manager` keeps sending them, and this is the check every guide points
+ * at as the reliable one. Order matters — strip the longest tokens first.
+ */
+function stripMultiCharTokens(presets: string): string {
+  return presets
+    .replace(/transform-[0-9a-f]*/g, "")
+    .replace(/upscale_[a-z0-9_]*/g, "")
+    .replace(/mp3/g, "")
+    .replace(/u[2-8]|t[1248ghij]/g, "")
+    .replace(/pr/g, "");
 }
 
 /**

package/src/palette.ts

@@ -87,7 +87,8 @@ export function getTextColorForBackground(
   return textColorForHex(hex);
 }
 
-function textColorForHex(hex: string): "#000000" | "#FFFFFF" {
+/** Luminancia relativa WCAG de un hex. 0 = negro, 1 = blanco. */
+export function relativeLuminance(hex: string): number {
   const h = hex.replace("#", "");
   const r = Number.parseInt(h.slice(0, 2), 16) / 255;
   const g = Number.parseInt(h.slice(2, 4), 16) / 255;
@@ -95,8 +96,68 @@ function textColorForHex(hex: string): "#000000" | "#FFFFFF" {
   // sRGB → linear
   const lin = (c: number) =>
     c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
-  const L = 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
-  return L > 0.5 ? "#000000" : "#FFFFFF";
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/**
+ * Razón de contraste WCAG entre dos luminancias: `(L1 + 0.05) / (L2 + 0.05)`,
+ * con la más clara arriba. 1 = idénticos, 21 = negro contra blanco.
+ */
+export function contrastRatio(l1: number, l2: number): number {
+  const [hi, lo] = l1 >= l2 ? [l1, l2] : [l2, l1];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Negro o blanco, el que **de verdad** contraste más sobre este fondo.
+ *
+ * ⚠️ CORREGIDO 2026-08-17. Antes decidía con `L > 0.5`, y **0,5 no es el punto
+ * de empate**. Igualando las dos razones de contraste:
+ *
+ *     (1 + 0.05) / (L + 0.05)  =  (L + 0.05) / 0.05
+ *     (L + 0.05)²              =  0.0525
+ *     L                        =  0.1791…
+ *
+ * Entre **0,179 y 0,5** el código viejo elegía BLANCO cuando negro contrastaba
+ * más — una banda ancha, y justo donde caen los colores de marca saturados.
+ * Medido sobre cuatro paletas reales de producción: **8 swatches** en esa banda.
+ * El peor, el dorado dominante `#CA9528`: devolvía blanco a **2,68:1** cuando
+ * negro da **7,84:1**. 2,68 no pasa AA ni para texto grande.
+ *
+ * No se cambia el umbral por 0,179: se **calculan las dos razones y gana la
+ * mayor**. Un umbral es una constante que hay que mantener correcta; la
+ * comparación es correcta por construcción.
+ *
+ * ⚠️ Esto elige el MEJOR de dos, no garantiza que alcance. Sobre un fondo de
+ * luminancia media el mejor par puede quedar por debajo de 4,5:1 igual — para
+ * eso está {@link bestTextContrast}, que además devuelve el número.
+ */
+function textColorForHex(hex: string): "#000000" | "#FFFFFF" {
+  return bestTextContrast(hex).color;
+}
+
+/**
+ * Igual que el color recomendado, pero devuelve también **la razón lograda** y
+ * si pasa AA — para que quien lo use pueda decidir con el número a la vista en
+ * vez de asumir que alcanzó.
+ */
+export function bestTextContrast(hex: string): {
+  color: "#000000" | "#FFFFFF";
+  ratio: number;
+  passesAA: boolean;
+  passesAALarge: boolean;
+} {
+  const L = relativeLuminance(hex);
+  const onBlack = contrastRatio(L, 0);
+  const onWhite = contrastRatio(L, 1);
+  const useBlack = onBlack >= onWhite;
+  const ratio = useBlack ? onBlack : onWhite;
+  return {
+    color: useBlack ? "#000000" : "#FFFFFF",
+    ratio,
+    passesAA: ratio >= 4.5,
+    passesAALarge: ratio >= 3,
+  };
 }
 
 /**

package/src/slots.ts

@@ -53,6 +53,13 @@ export type SlotResolution = {
 const DEFAULT_TTL_MS = 60_000;
 const cache = new Map<string, { fetchedAt: number; value: SlotDTO | null }>();
 
+// Deliberately the generated `run.app` URL, NOT the branded
+// `api.nitida.gofuture.space` the docs publish — this is the fallback for a
+// caller that configured nothing, so it should be the address with the fewest
+// moving parts. Cloud Run guarantees the generated URL forever; the branded name
+// is an additional domain mapping that depends on DNS and a managed certificate
+// (and on 2026-08-17 we learned how many ways those two can go sideways —
+// doc 242 §6.3). Both names hit the same service and return identical bodies.
 let endpoint = "https://aquienpz-asset-manager-nlchzy26qa-uc.a.run.app";
 let apiKey: string | null = null;
 let tenantCode: string | null = null;