@nitida/sdk 0.24.1 → 0.25.0

package/skills/nitida-sdk/SKILL.md

@@ -122,7 +122,7 @@ speed/quality argument, as a number.
 | Full-bleed retina hero | `2560` / `3840` — **only if the master reaches it** |
 
 ```tsx
-// Sin `quality`: auto-quality sondea el MÁSTER ⇒ una sola compresión.
+// No `quality`: auto-quality probes the MASTER ⇒ a single compression.
 <img
   src={getTransformUrl(asset, { format: "webp", width: 800 })}
   srcSet={getTransformSrcSet(asset, [400, 800, 1200, 1600], { format: "webp" })}
@@ -130,10 +130,10 @@ speed/quality argument, as a number.
 />
 ```
 
-⚠️ **Fijate que NO lleva `quality`.** Un `quality` numérico activa el atajo que
-lee una variante ya comprimida — ver la advertencia de abajo. Si de verdad
-necesitás fijarlo (un presupuesto de bytes duro), es un opt-in consciente, no el
-default que se copia sin leer.
+⚠️ **Note there is NO `quality`.** A numeric `quality` switches on the shortcut
+that reads an already-compressed variant — see the warning below. If you really
+do need to pin it (a hard byte budget), make that a deliberate opt-in, not a
+default copied without reading.
 
 **`sizes` is what makes the phone pick 800 and the desktop 1600 from the same
 tag.** Omit it and the browser assumes `100vw`, fetches the large candidate for
@@ -218,21 +218,19 @@ Output: `https://8ok.uk/<tenantId.toString(36)>/v/<sha16>-v.mp4`.
 
 **Audio IS supported (updated 2026-07-01 — verify against the SDK types, this used to say "not supported").** The platform recognizes `kind: "image" | "video" | "document" | "audio" | "other"` and ships an **`mp3`** variant preset (`VariantPreset` in `@nitida/asset-client`). Uploads are hash-deduped (byte-identical re-uploads return the existing sha — that's *byte* dedup, NOT semantic "find a similar track"). `nt.upload` also accepts an `audioTrack` on video-composition calls. Serve via the `mp3` preset / `original`. Confirm the current preset/kind list in `node_modules/@nitida/asset-client/dist/index.d.ts` before relying on a specific ext.
 
-> ✅ **FIXED 2026-08-17 (#230/#231): you no longer have to pass `contentType` to avoid
-> `kind:"other"`.** This section used to insist on
-> `upload(bytes, { contentType: "audio/mpeg", fileName: "track.mp3" })` as a *defence*. Two
-> independent holes made that necessary and both are closed:
+> ✅ **Fixed in the 2026-08-17 deploy: you no longer have to pass `contentType` to avoid
+> `kind:"other"`.** Passing `upload(bytes, { contentType: "audio/mpeg", fileName: "track.mp3" })`
+> used to be a *defence*. Two independent holes made that necessary and both are closed:
 >
 > - **The mime round-trip lost the type.** Presign derives the stored extension with
 >   `mime.extension(body.mime)`, so `audio/mpeg` became `.mpga` — and the server's hand-written
 >   ext→mime `switch` did not know `.mpga`, so it came back as `application/octet-stream` ⇒
->   `kind:"other"` ⇒ no variants. That swallowed **104 MP3 uploads**. `detectMime` now derives from
->   the same `mime-types` table that produced the extension, closing the whole class by construction
->   (7 broken round-trips fixed: `mpga`, `heif`, `adts`, `tif`, `bmp`, `svg`, `flac`), and
->   `test/mime-roundtrip.test.ts` keeps it closed.
+>   `kind:"other"` ⇒ no variants, silently, for every MP3 uploaded that way. The server now derives
+>   the mime from the same table that produced the extension, closing the whole class by
+>   construction — `mpga`, `heif`, `adts`, `tif`, `bmp`, `svg` and `flac` all round-trip.
 > - **Genuinely untyped uploads are rescued by their bytes.** When the key implies
->   `application/octet-stream`, `/process` sniffs the magic bytes (`sniffMagicMime`) and processes
->   the file as what it actually is.
+>   `application/octet-stream`, the server sniffs the magic bytes and processes the file as what it
+>   actually is.
 >
 > Passing `contentType` + `fileName` is still *good practice* — it is the cheapest possible signal
 > and it decides the stored extension. It is no longer load-bearing.
@@ -264,7 +262,7 @@ If you are uploading to **archive** something (not just to serve it), three serv
 
 The client's `PRESET_EXT.original` is the literal `"bin"`, so `getAssetUrl({sha}, "original")` **without `mime`** emits `-o.bin` while a PNG is really stored at `-o.png` → 404, always.
 
-> ✅ **FIXED 2026-08-17 (doc 240 §4.3 + §4.4). Pass the whole DTO and it is simply right:**
+> ✅ **Fixed in the 2026-08-17 deploy. Pass the whole DTO and it is simply right:**
 >
 > ```ts
 > const asset = await nt.assets.get(id);
@@ -294,32 +292,26 @@ The client's `PRESET_EXT.original` is the literal `"bin"`, so `getAssetUrl({sha}
 await nt.assets.regenerate(assetId, { presets: ["original"] });
 ```
 
-⚠️ **Elegir mal `presets` NO destruye nada — pero rompe una API y no la otra.** Verificado
-2026-08-17 contra producción, sobre un asset del **16-jun** con `presets:"q"` (sólo miniatura):
-**su `raw` sigue existiendo (HTTP 200), dos meses después.**
+⚠️ **Choosing `presets` badly destroys nothing — but it breaks one API and not the other.**
+Verified 2026-08-17 against a live asset ingested two months earlier with `presets:"q"` (thumbnail
+only): its raw upload was still there, HTTP 200.
 
-La limpieza conserva el `raw` de **cualquier** sha referenciado por una fila de asset, incluidas las
-borradas en suave. **Mientras exista la fila, los bytes originales están.**
+Cleanup keeps the raw bytes of **any** sha referenced by an asset row, soft-deleted rows included.
+**While the row exists, the original bytes exist.**
 
-⇒ lo que realmente pasa si pediste `["thumb"]` y necesitabas la escalera:
+⇒ what actually happens if you asked for `["thumb"]` and needed the ladder:
 
-| lo que llamás | qué obtenés |
+| what you call | what you get |
 |---|---|
-| `getAssetUrl(asset, "md")` | **404** — esa variante nunca se generó |
-| `/t/…width=1280/<sha>.webp` | **200** — se genera al vuelo desde el raw |
-| `hasPreset(asset, "lg")` | `false`, correctamente |
+| `getAssetUrl(asset, "md")` | **404** — that variant was never generated |
+| `/t/…width=1280/<sha>.webp` | **200** — generated on the fly from the raw |
+| `hasPreset(asset, "lg")` | `false`, correctly |
 
-Una API te dice que no existe y la otra te la entrega. **Eso** es lo caro: no la pérdida, la
-incoherencia — más un cómputo en frío la primera vez que alguien pide cada tamaño.
+One API tells you it does not exist and the other hands it to you. **That** is the expensive part —
+not the loss, the incoherence — plus a cold compute the first time anyone asks for each size.
 
-**Se arregla en cualquier momento** con `regenerate({presets:[...]})`, que lee del raw. No hay
-ventana que se cierre.
-
-> ⚠️ **CORREGIDO 2026-08-17. La versión anterior de este párrafo decía que «los bytes del raw pueden
-> ya ser irrecuperables» si la primera ingesta no pidió `original`.** Era falso, y venía de una
-> hipótesis escrita como diagnóstico: la corrida del 2026-08-07 observó que `regenerate` no producía
-> el `original` y concluyó *«consistent with `raw/` already being gone»*. Nadie comprobó el raw. Al
-> comprobarlo, está. Lo que sí sigue en pie de esa corrida es la disciplina de abajo.
+**It is fixable at any time** with `regenerate({presets:[...]})`, which reads from the raw. No
+window closes.
 
 **Verify, don't assume.** Round-trip every archived file: download the `original` URL from the API
 and compare its SHA-256 to the local file. "97 uploaded, 0 failed" was true and meaningless.
@@ -333,18 +325,19 @@ and compare its SHA-256 to the local file. "97 uploaded, 0 failed" was true and
 
 `presets` is documented as a concatenation of **one-character** codes, and membership is a
 one-character `includes`. It used to carry multi-character tokens as well (`transform-3da0019…`,
-`probe`), and every one of them answered `true` for presets that do not exist. Counted on live
-rows: **16 299** assets were told they had an `original` they did not have — sending callers to
-exactly the 404 that `oext` came to remove — plus 16 479 phantom `aiproxy` and 487 phantom `sm`/`md`.
+`probe`), and every one of them answered `true` for presets that do not exist. On a corpus written
+by those servers the majority of rows are polluted, and a large minority are told they have an
+`original` they do not — sending callers to exactly the 404 that `oext` came to remove. Phantom
+`aiproxy` is affected at the same order of magnitude; `sm`/`md` far less.
 
-✅ **Fixed 2026-08-17 (#228) on both sides:** the server emits only the 1-char vocabulary (plus the
+✅ **Fixed in the 2026-08-17 deploy, on both sides:** the server emits only the 1-char vocabulary (plus the
 sanctioned `mp3` token, which is deliberate and stays), and `hasPreset` strips multi-char tokens
 before the `includes`. **`hasPreset(dto, preset)` remains the recommended existence check** — it is
 the only field present on every response shape, including the slim list/resolver one that carries no
 `variants` at all.
 
-⚠️ **Against a server deploy older than 2026-08-17 the contaminated strings are still being sent**
-(62 % of live rows had one). The client-side strip covers you; a hand-rolled
+⚠️ **Against a server deploy older than 2026-08-17 the contaminated strings are still being sent**,
+on the majority of rows. The client-side strip covers you; a hand-rolled
 `dto.presets.includes("o")` does not.
 
 ⚠️ **`mp3` is a real, multi-char token in the vocabulary on purpose.** Any substring test you write
@@ -508,15 +501,15 @@ needed. Reproduce there before debugging any of these by hand.
 | **400** on an image URL | width not on `TRANSFORM_WIDTHS` ladder |
 | **410** on a video URL | used `/t/` (transform) for a stored video — use `getAssetUrl(...,'video')` |
 | **404** on a video URL | decimal tenant prefix (`/10/v/`) instead of base36 (`/a/v/`) — call `setTenantId` + `getAssetUrl`. Tenant 12 → `/c/v/` |
-| `process returned no assetId` | fixed 2026-08-16 — you are on a server deploy older than that, §7.2 |
+| `process returned no assetId` | fixed in the 2026-08-16 deploy — you are on a server deploy older than that, §7.2 |
 | `waitReady timeout` on a video | a transcode + HLS ladder takes 1–2 min; the default `timeoutMs` is 5 min but a 4K source can beat it. Raise it, §7.2 |
 | the direct PUT fails with a bare network error | your origin is not in the storage bucket's CORS policy — ours to fix, §7.1 |
-| `nt.assets.variants()` returns `[]` | fixed 2026-08-17 (#225) — you are on a server deploy older than that. Existence from `dto.presets` + `hasPreset` works on every version |
-| `hasPreset` says a preset exists and its URL 404s | fixed 2026-08-17 (#228) — an old server sends multi-char tokens in `presets`; a current `@nitida/asset-client` strips them, a hand-rolled `includes` does not, §3b-bis |
+| `nt.assets.variants()` returns `[]` | fixed in the 2026-08-17 deploy — you are on a server deploy older than that. Existence from `dto.presets` + `hasPreset` works on every version |
+| `hasPreset` says a preset exists and its URL 404s | fixed in the 2026-08-17 deploy — an old server sends multi-char tokens in `presets`; a current `@nitida/asset-client` strips them, a hand-rolled `includes` does not, §3b-bis |
 | `tenant_not_found` from a service | tenant rows missing, or the 60s tenant-config cache is stale |
 | `original` 404s | (a) never written — `presets` omitted `"original"` at ingest, or the asset is a VIDEO (always dropped, §7.3); (b) `getAssetUrl` called with a bare `{sha}` → the `-o.bin` sentinel; (c) called with `{sha, mime}` against an old server, so it guessed the extension. Pass the whole DTO from `nt.assets.get(id)` — see §3b |
 | "uploaded OK" but nothing to restore | `["thumb"]`-style presets store no original; verify by SHA-256 round-trip, not by upload count — see §3b |
-| audio stored as `kind:"other"` | fixed 2026-08-17 (#230/#231) — the ext→mime round-trip lost `.mpga`, and untyped bytes are now sniffed. Against an older server deploy, upload with an explicit `contentType:"audio/mpeg"`. Rows misclassified **before** the fix stay that way by decision, §3 |
+| audio stored as `kind:"other"` | fixed in the 2026-08-17 deploy — the ext→mime round-trip lost `.mpga`, and untyped bytes are now sniffed. Against an older server deploy, upload with an explicit `contentType:"audio/mpeg"`. Rows misclassified **before** the fix stay that way by decision, §3 |
 
 > Source of truth for deeper detail: the published docs — <https://nitida.gofuture.space/guides/advanced/>,
 > <https://nitida.gofuture.space/guides/troubleshooting/>, <https://nitida.gofuture.space/start/credentials/> —

package/src/index.ts

@@ -4,8 +4,8 @@
  *
  * One ergonomic facade over the underlying packages
  * (`@nitida/asset-client` URL builders + `@aquienpz/asset-uploader-web`
- * + the slot resolver). Auth is a Better Auth API key (`amk_rt_*`)
- * issued by aquienpz `bootstrap-project.ts`; tenant scope comes from
+ * + the slot resolver). Auth is a bearer API key (`amk_rt_*`), issued
+ * per tenant when the tenant is created; tenant scope comes from
  * the key's metadata (`X-Tenant-Code` is log-only).
  *
  * Usage:
@@ -14,8 +14,8 @@
  *
  *   const aq = new NitidaClient({
  *     endpoint: "https://api.nitida.gofuture.space",
- *     apiKey:   process.env.ASSET_MANAGER_RUNTIME_KEY!,
- *     tenantCode: "realtyone-cr",
+ *     apiKey:   process.env.AQUIENPZ_API_KEY!,   // amk_rt_* — server-only
+ *     tenantCode: "acme-co",
  *     cdnBase: "https://8ok.uk",  // optional override
  *     tenantId: 4,                 // required for tenant-prefixed URLs
  *   });
@@ -86,7 +86,7 @@ export type NitidaClientOptions = {
    */
   endpoint: string;
   /**
-   * Better Auth API key with the `amk_rt_*` prefix.
+   * Bearer API key with the `amk_rt_*` prefix.
    *
    * **Server-only.** Omit when constructing from `@nitida/sdk/web` —
    * your BFF / route handler injects the bearer header in proxy mode.
@@ -111,8 +111,8 @@ export type NitidaClientOptions = {
    * Tenant's HMAC signing key for transform URLs (Phase 3). Required
    * only when calling `aq.transform(asset, opts, { sign: true })`.
    *
-   * Generated server-side per tenant (see `infra/sql/tenants_signed_transforms.sql`);
-   * fetch via `GET /admin/tenants/:id` with an admin key. **Keep it
+   * 32 random bytes, generated server-side on tenant creation; fetch
+   * via `GET /admin/tenants/:id` with an admin key. **Keep it
    * server-side only** — do not ship in `NEXT_PUBLIC_*` env vars. Sign
    * URLs from a BFF route handler, or pre-sign at build time.
    */
@@ -190,9 +190,19 @@ function authHeaders(opts: NitidaClientOptions): Record<string, string> {
 // Re-exports (so consumers don't double-import from asset-client)
 // ---------------------------------------------------------------------------
 
+// This barrel is COMPLETE on purpose: every public symbol of
+// `@nitida/asset-client` is reachable from `@nitida/sdk`, so a consumer never
+// has to know which of the two packages a helper happens to live in. It had
+// drifted to 30 of 53 — the gap silently included `TRANSFORM_WIDTHS` and
+// `TransformWidth`, which both READMEs tell you to import precisely so an
+// off-ladder width fails at compile time instead of returning 400, and the
+// palette helpers the README imports from here by name.
 export type {
   AssetDTO,
+  AssetPalette,
   AssetVariant,
+  HlsRung,
+  PaletteSwatch,
   ResolveSlotOptions,
   SignedTransformOptions,
   SlotDTO,
@@ -202,24 +212,47 @@ export type {
   TransformFormat,
   TransformGravity,
   TransformOptions,
+  TransformWidth,
   VariantPreset,
 } from "@nitida/asset-client";
 export {
+  bestTextContrast,
   computeVariantDimensions,
+  configureSlotResolver,
+  contrastRatio,
   extractAssetSha,
+  getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getCdnBase,
+  getHlsLadder,
   getHlsStreamingUrl,
+  getPaletteBlurBackground,
+  getPaletteCssVars,
   getSignedTransformUrl,
   getTenantId,
+  getTextColorForBackground,
   getTransformSrcSet,
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hlsLadderAlignment,
+  invalidateSlotCache,
+  iteratePaletteSwatches,
+  PRESET_EXT,
+  PRESET_LONG,
+  PRESET_MAX_DIM,
+  PRESET_SHORT,
+  pickAmbientBackground,
+  relativeLuminance,
+  resolveSlot,
+  resolveSlots,
   serializeTransform,
+  setCdnBase,
   setTenantId,
   signTransformUrl,
+  TRANSFORM_WIDTHS,
 } from "@nitida/asset-client";
 
 // ---------------------------------------------------------------------------
@@ -409,7 +442,7 @@ export type UploadVideoOptions = {
   hls?: boolean;
   /**
    * `true` → when the uploaded MP4 is ALREADY web-safe (H.264 + yuv420p),
-   * re-mux the `video` variant with `-c copy` instead of re-encoding. Use for
+   * re-mux the `video` variant instead of re-encoding it. Use for
    * delivery-ready uploads (the bytes are already H.264 High / yuv420p /
    * +faststart / capped bitrate) to skip a wasteful re-encode + generational
    * quality loss. Falls back to a full re-encode automatically when the source
@@ -435,8 +468,8 @@ export type PresignUploadUrlOptions = {
   presets?: VariantPreset[];
   /**
    * Pre-compression size of the source (useful when the browser ran
-   * compressorjs / heic2any before computing `bytes`). Surfaces in admin
-   * dashboards under `assets.client_original_bytes`.
+   * compressorjs / heic2any before computing `bytes`). Recorded
+   * server-side, so the savings show up in the admin usage dashboards.
    */
   clientOriginalBytes?: number;
   /** VIDEO-only delivery knobs forwarded into `/assets/process`. See {@link UploadVideoOptions}. */
@@ -571,8 +604,8 @@ class AssetsApi {
    *   const v = await aq.assets.variants(logoId);
    *   v.map((x) => x.preset);  // → ("thumb" | "sm" | … | "original")[]
    *
-   * ⚠️ Returns `[]` — not an error — against a server deploy older than the
-   * 2026-08-17 deploy, which never sent the field (doc 240 §4.3). An empty
+   * ⚠️ Returns `[]` — not an error — against a server older than the
+   * 2026-08-17 release, which never sent the field at all. An empty
    * array is therefore "no variants OR old server". For a plain existence
    * check prefer `hasPreset(dto, preset)` on `dto.presets`, which every server
    * version sends; use this when you need the URLs and sizes.
@@ -601,12 +634,13 @@ class AssetsApi {
    * Passing no presets re-runs the FULL default pipeline for that
    * asset's kind (thumb+sm+md+lg for images, poster+video for video).
    *
-   * If the asset was uploaded original-only and the cleanup job has
-   * already reaped `raw/`, the route falls back to reading the source
-   * bytes from `variants/o.<ext>` — no need to re-upload.
+   * If the asset was uploaded original-only and the ~24 h grace window
+   * on the uploaded bytes has already closed, the route falls back to
+   * reading the source bytes from the permanent `original` variant —
+   * no need to re-upload.
    *
    * Video presets are filtered to `["poster","video","aiproxy"]` and
-   * dispatched to the background job (the call returns immediately
+   * dispatched to a background job (the call returns immediately
    * with a dispatch handle; poll `aq.assets.get(id).status` for
    * completion).
    */
@@ -916,8 +950,8 @@ export type UploadOptions = {
   /**
    * Max time to wait for the asset to transition to `ready` (or `failed`)
    * after dispatch. Default `5 * 60_000` (5 min). Bump higher for large
-   * videos / HLS transcodes — aquienpz processing time scales with input
-   * size and per-instance CPU.
+   * videos / HLS transcodes — processing time scales with input size,
+   * and with how much other work the platform is doing at that moment.
    *
    * Throws `Error("waitReady timeout for <id>")` if the deadline passes
    * without the asset transitioning. The asset row stays in aquienpz
@@ -1007,11 +1041,11 @@ export type UsageWindow = {
    * encode passes, so a 7-rung HLS ladder over a 2-minute clip books 14.
    *
    * A re-encode of a video already ingested counts AGAIN. That is the point:
-   * `assets.assets` cannot report it, because its insert is
-   * `ON CONFLICT DO UPDATE` and a re-encode creates no row there.
+   * an asset count cannot report it, because re-encoding an asset that already
+   * exists creates no new asset.
    *
-   * A stream copy (`-c copy` passthrough, an idempotent cache skip) books
-   * nothing, so a tenant that ran no encoder reads `0` — and that `0` is real.
+   * A stream copy (`video: { passthrough: true }`, or an idempotent cache skip)
+   * books nothing, so a tenant that ran no encoder reads `0` — and that `0` is real.
    */
   videoMinutes: number;
   /** Encode passes behind `videoMinutes`. 0 when nothing was encoded. */
@@ -1270,7 +1304,7 @@ export class NitidaClient {
    * images).
    *
    * On the first request the route returns **202 Accepted** with
-   * `Retry-After: 10` while the Job runs (typically 5-30 s for a
+   * `Retry-After: 10` while the encode runs (typically 5-30 s for a
    * short clip). The response body includes `outputUrl` which is the
    * eventual CDN URL — poll the same transform URL after the
    * retry-after window to get a 302 redirect to it.
@@ -1342,8 +1376,8 @@ export class NitidaClient {
    *
    * ⚠️ `presets` decides what exists FOREVER. Omit it and only `original` is written; ask for
    * `["thumb"]` and the bytes you just uploaded are **not retrievable**. A variant not requested in
-   * this first ingest cannot be added later once the cleanup job reaps `raw/` — measured once as
-   * "97 files archived successfully, zero recoverable".
+   * this first ingest cannot be added later once the ~24 h grace window on the uploaded bytes
+   * closes — measured once as "97 files archived successfully, zero recoverable".
    *
    * @example Deliver an image on a site (the responsive ladder)
    * ```ts
@@ -1374,7 +1408,7 @@ export class NitidaClient {
    * @example Video — and what does NOT work there
    * ```ts
    * // `original` is accepted and then silently DROPPED: /assets/process filters video presets to
-   * // {poster, video, aiproxy, probe} before dispatching the transcode Job.
+   * // {poster, video, aiproxy, probe} before dispatching the background transcode.
    * await aq.upload(clip, { fileName: "tour.mp4", presets: ["poster", "video"] });
    *
    * // Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost encode

package/src/server/index.ts

@@ -10,9 +10,9 @@
  *   import { NitidaClient } from "@nitida/sdk/server";
  *
  *   const aq = new NitidaClient({
- *     endpoint:   process.env.ASSET_MANAGER_URL!,
- *     apiKey:     process.env.ASSET_MANAGER_API_KEY!,   // <- required
- *     tenantCode: "realtyone-cr",
+ *     endpoint:   process.env.AQUIENPZ_URL!,
+ *     apiKey:     process.env.AQUIENPZ_API_KEY!,   // <- required
+ *     tenantCode: "acme-co",
  *     tenantId:   1,
  *     // signingKey: optional, only for `aq.transform(..., { sign: true })`
  *   });
@@ -32,9 +32,11 @@
  *     globally; File-API workflows are documented on the /web subpath instead)
  *
  * What's NOT here (use `@nitida/sdk/web` instead):
- *   - `createWebUploader` (multipart UploadTask with IndexedDB resume)
  *   - `compressImage` (browser-side compressorjs + heic2any)
  *
+ * And what exists nowhere: there is no `createWebUploader`. Multipart is not
+ * exposed from any subpath — `aq.upload()` is the supported path.
+ *
  * Stripe/Cloudinary historically shipped two separate packages
  * (`stripe` vs `@stripe/stripe-js`, `cloudinary` vs `@cloudinary/url-gen`)
  * for this split. Modern providers (Vercel Blob, Uploadthing, Better
@@ -51,9 +53,9 @@ import { NitidaClient as BaseNitidaClient, type NitidaClientOptions } from "..";
  * Cloud Run, Vercel Functions, edge runtimes, BFFs).
  *
  *   const aq = new NitidaClient({
- *     endpoint:   process.env.ASSET_MANAGER_URL!,
- *     apiKey:     process.env.ASSET_MANAGER_API_KEY!,
- *     tenantCode: "realtyone-cr",
+ *     endpoint:   process.env.AQUIENPZ_URL!,
+ *     apiKey:     process.env.AQUIENPZ_API_KEY!,
+ *     tenantCode: "acme-co",
  *     tenantId:   1,
  *   });
  */

package/src/web/index.ts

@@ -13,7 +13,7 @@
  *     // Point at your BFF route — the SDK calls
  *     // `${endpoint}/assets/by-hash/...`, `${endpoint}/slots/...`, etc.
  *     endpoint:   "/api/am",          // relative ⇒ same-origin proxy
- *     tenantCode: "realtyone-cr",
+ *     tenantCode: "acme-co",
  *     tenantId:   1,
  *     // NO apiKey — the type strips it. Your BFF injects the bearer.
  *   });
@@ -28,7 +28,7 @@
  *     return fetch(url, {
  *       headers: {
  *         Authorization: `Bearer ${process.env.AQUIENPZ_API_KEY!}`,
- *         "X-Tenant-Code": "realtyone-cr",
+ *         "X-Tenant-Code": "acme-co",
  *       },
  *     });
  *   }
@@ -64,7 +64,7 @@ import { NitidaClient as BaseNitidaClient, type NitidaClientOptions } from "..";
  *
  *   const aq = new NitidaClient({
  *     endpoint:   "/api/am",          // OK: relative → same-origin BFF
- *     tenantCode: "realtyone-cr",
+ *     tenantCode: "acme-co",
  *     tenantId:   1,
  *     // apiKey:  "amk_rt_...",       // ERROR: TS error: not assignable
  *   });
@@ -150,9 +150,9 @@ export {
 // ---------------------------------------------------------------------------
 //
 // Wraps `@nitida/asset-compressor-web` with the SDK's
-// `DEFAULT_COMPRESSION_OPTIONS` — values derived from the realtyone-cr
-// webapp's production tuning (LISTING_STANDARD_*: quality 0.80, max-edge
-// 3840px, WebP output, 5MB PNG→JPEG threshold, strict mode). Those defaults
+// `DEFAULT_COMPRESSION_OPTIONS` — values tuned against a production
+// photo-upload workload (quality 0.80, max-edge 3840px, WebP output,
+// 5MB PNG→JPEG threshold, strict mode). Those defaults
 // differ from `@nitida/asset-compressor-web`'s own defaults (0.85 / 2880 /
 // convertSize=0) which target a slightly different audience; SDK callers
 // get the webapp-tuned values, package-direct callers keep theirs.
@@ -184,17 +184,16 @@ export type CompressStage =
 
 /**
  * Subset of compressorjs options exposed by the SDK. Matches the
- * webapp's `DEFAULT_COMPRESSION_OPTIONS` shape from the realtyone-cr
- * production back-office uploader.
+ * `DEFAULT_COMPRESSION_OPTIONS` shape below.
  */
 export type CompressOptions = {
-  /** 0..1. Default 0.80 (`LISTING_STANDARD_IMAGE_QUALITY / 100`). */
+  /** 0..1. Default 0.80. */
   quality?: number;
-  /** Output format. Default `"image/webp"` (`DEFAULT_IMAGE_TARGET_FORMAT`). */
+  /** Output format. Default `"image/webp"`. */
   mimeType?: "image/jpeg" | "image/webp";
-  /** Max edge in pixels. Default 3840 (`LISTING_STANDARD_IMAGE_WIDTH`). */
+  /** Max edge in pixels. Default 3840. */
   maxWidth?: number;
-  /** Default 3840 (`LISTING_STANDARD_IMAGE_HEIGHT`). */
+  /** Max edge in pixels. Default 3840. */
   maxHeight?: number;
   /**
    * compressorjs `convertSize`: PNG > this byte count auto-converts to
@@ -215,9 +214,9 @@ export type CompressOptions = {
 };
 
 /**
- * Webapp-tuned defaults (LISTING_STANDARD_*). These intentionally differ
- * from `@nitida/asset-compressor-web`'s package-level defaults — the
- * SDK overrides at call time.
+ * Defaults tuned against a production photo-upload workload. These
+ * intentionally differ from `@nitida/asset-compressor-web`'s
+ * package-level defaults — the SDK overrides at call time.
  */
 export const DEFAULT_COMPRESSION_OPTIONS: Required<
   Omit<CompressOptions, "keepOriginalDimensions" | "convertHeic" | "onProgress">
@@ -274,8 +273,8 @@ export async function compressImage(
   // String indirection defeats bundler static-analysis of dynamic
   // imports — Turbopack/webpack will leave this for the runtime to
   // resolve instead of failing the build when the optional peer dep
-  // isn't installed. See feedback_bun_compile_dynamic_imports (same
-  // trick used in reverse to opt OUT of bundling).
+  // isn't installed. (The same trick is used in reverse elsewhere in
+  // this SDK to opt OUT of bundling.)
   const compressorPkg = "@nitida/asset-compressor-web";
   const { compressImage: doCompress } = (await import(
     /* @vite-ignore */ /* webpackIgnore: true */ compressorPkg