@nitida/asset-client 0.16.0 → 0.16.2

package/src/transform.ts

@@ -2,10 +2,9 @@
  * On-the-fly transform URL builder.
  *
  * Mirrors the server's DSL canonicalizer byte-for-byte so a URL generated
- * here hashes to the same R2 cache key as the server's canonical form.
+ * here hashes to the same cache key as the server's canonical form.
  *
- * Canonicalization rules (keep in sync with
- * `apps/asset-manager/src/features/assets/transform.dsl.ts`):
+ * Canonicalization rules (kept in sync with the server):
  *   - Drop entries whose value is `undefined`
  *   - Sort keys alphabetically
  *   - Numbers rendered without leading zeros or trailing dots
@@ -23,7 +22,7 @@ import type { AssetDTO } from "./index";
 import { getCdnBase } from "./index";
 
 /**
- * Widths the CDN edge whitelists (DoS guard — see `apps/cdn-proxy` WHITELIST_WIDTHS).
+ * Widths the CDN edge whitelists (DoS guard).
  * Requesting any OTHER width returns HTTP 400 at the edge (unsigned URLs). These are the
  * 1× base ladder values; DPR ×2/×3 multiples are applied + whitelisted server-side. Import
  * this instead of hardcoding magic widths so an unsupported size is caught in review/IDE.
@@ -77,9 +76,9 @@ export type TransformOptions = {
   height?: number;
   /** Resize fit mode. Default `cover` server-side. */
   fit?: TransformFit;
-  /** Crop gravity. `auto` uses sharp's `attention` strategy. */
+  /** Crop gravity. `auto` picks the region with the most visual salience. */
   gravity?: TransformGravity;
-  /** Output format. `auto` → policy decides (see asset-manager bench). */
+  /** Output format. `auto` → the platform's policy decides. */
   format?: TransformFormat;
   /** Output quality. `auto` → format-specific default. */
   quality?: "auto" | number;
@@ -90,16 +89,15 @@ export type TransformOptions = {
    *
    *   - `removebg`: remove the background; output is a transparent PNG
    *     of the foreground subject. Forces `format=png` regardless of
-   *     other format hints. Runs U²-Net ONNX locally (or BRIA via
-   *     Replicate when `BG_REMOVAL_BACKEND=replicate`). Single cache
-   *     miss per (sha, dsl) tuple; subsequent identical DSLs serve
-   *     from R2 — no inference, no per-image cost.
+   *     other format hints. A single cache miss per (sha, dsl) tuple;
+   *     subsequent identical DSLs serve from cache — no inference, no
+   *     per-image cost.
    *
-   *   - `genfill`: aspect-extension outpaint via Flux-Fill Pro on
-   *     Replicate. Requires BOTH `width` and `height` — the server
+   *   - `genfill`: aspect-extension outpaint. Requires BOTH `width`
+   *     and `height` — the server
    *     fits the source centered into the target canvas and outpaints
    *     the gutters. Output is PNG (forced) at exactly target dims.
-   *     ~$0.05/image first time; same R2 cache as removebg after.
+   *     ~$0.05/image first time; same cache as removebg after.
    *     Primary use case: building OG cards (1200×630) from portrait
    *     listing photos without awkward edge mirroring.
    */
@@ -121,7 +119,7 @@ export type TransformOptions = {
  * the escape hatch for SIGNED URLs that need an off-ladder custom width.
  *
  * The edge whitelist only rejects off-ladder widths on UNSIGNED URLs; a valid
- * `?sig=` earns the whitelist bypass at the worker (the asset-manager still
+ * `?sig=` earns the whitelist bypass at the edge (the server still
  * does the real HMAC check). So a custom width is ONLY safe when the URL is
  * signed — hence this type is accepted exclusively by the signing helpers
  * ({@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`),
@@ -181,10 +179,10 @@ export function serializeTransform(opts: SignedTransformOptions): string {
 function extForOptions(opts: SignedTransformOptions): string {
   // effect=removebg forces PNG output server-side (needs alpha).
   if (opts.effect === "removebg") return "png";
-  // effect=genfill defaults to WebP (12× lighter than the raw Flux-Fill
+  // effect=genfill defaults to WebP (12× lighter than the raw generated
   // PNG output with no visible loss at q=85). Explicit `format=png`
   // opts back into lossless for print / marketing fold-outs. The server
-  // re-encodes Flux's PNG → target format before R2 cache.
+  // re-encodes the generated PNG → target format before caching.
   if (opts.effect === "genfill") {
     switch (opts.format) {
       case "png":
@@ -222,8 +220,8 @@ function extForOptions(opts: SignedTransformOptions): string {
  * Build a transform URL for a VIDEO asset. Same DSL shape as image
  * transforms; the server branches on the asset's `kind` column. Video
  * URLs use `.mp4` (default) or `.webm` extension and on cache miss the
- * server returns 202 Accepted while a Cloud Run Job encodes the clip;
- * subsequent GETs return 302 to the cached R2 object.
+ * server returns 202 Accepted while a background job encodes the clip;
+ * subsequent GETs return 302 to the cached object.
  *
  *   <video src={aq.transformVideo(asset, { width: 1080, height: 1920 })}
  *          autoPlay muted loop playsInline />
@@ -271,8 +269,8 @@ export function getVideoTransformUrl(
  * }
  * ```
  *
- * On first request the server returns 202 Accepted while a Cloud Run
- * Job transcodes the ladder (typically 1-3 min for a 90 s source);
+ * On first request the server returns 202 Accepted while a background
+ * job transcodes the ladder (typically 1-3 min for a 90 s source);
  * subsequent requests get 302 to the cached master.m3u8. Keep the
  * progressive MP4 as a fallback source for that window.
  *