@nitida/asset-client 0.17.0 → 0.18.1

package/dist/index.d.ts

@@ -1,3 +1,114 @@
+/**
+ * Signed URLs for PRIVATE assets — the `/a/{tenant}/…?exp&sig` tree.
+ *
+ * ## Who calls this, and who must not
+ *
+ * The tenant's BACKEND, which knows who the viewer is and holds the signing
+ * key. Never a browser: shipping the signing key to the client would let any
+ * visitor mint URLs for any private asset of that tenant, which is the whole
+ * property the tree exists to provide. This module is deliberately importable
+ * from anywhere — it runs on WebCrypto, so browsers, Node, Bun and Workers all
+ * work — and that convenience is exactly why the warning is here rather than
+ * in a doc nobody reads at the call site.
+ *
+ * ## Not the same signature as `signTransformUrl`
+ *
+ * `signTransformUrl` vouches for a WIDTH; this vouches for a VIEWER, until
+ * `exp`. They come from the same `signing_key` but not the same key material:
+ * the access key is derived (`HMAC(signing_key, "nitida/access/v1")`) so that
+ * no crafted transform path can be replayed as an access signature. The full
+ * argument lives beside the server implementation in `access-signing.ts`; the
+ * short version is that a shared payload with a prefix separator IS
+ * collidable, because both fields of the transform message are
+ * attacker-influenced path segments.
+ *
+ * ## `exp` is mandatory
+ *
+ * A signed URL that never expires is a public URL as soon as someone forwards
+ * it. There is no "no expiry" option here, and there will not be one.
+ */
+/**
+ * The per-tenant access key, derived from `signing_key`. Same value the origin
+ * computes and hands the edge — nothing needs to be stored or synchronised.
+ */
+declare function deriveAccessKey(signingKey: string): Promise<Uint8Array>;
+/**
+ * The signed message. Byte-identical to the server's `accessMessage` and the
+ * worker's — three implementations of one string, which is why all three pin
+ * the exact bytes in a test.
+ *
+ * `tenantPrefix` is the base36 segment as it appears in the URL, not the
+ * decimal id: tenant 10 lives at `/a/a/`, and the thing being vouched for is a
+ * path.
+ */
+declare function accessMessage(tenantPrefix: string, exp: number, resourcePath: string): string;
+type SignAccessOptions = {
+    /** Lifetime in seconds. Required — see the header. */
+    expiresInSeconds: number;
+    /** Injectable clock, for tests that need a URL already dead on arrival. */
+    nowSeconds?: number;
+};
+/**
+ * Turn a PUBLIC-tree URL into a signed PRIVATE-tree URL.
+ *
+ *   https://8ok.uk/5/v/<sha16>-lg.webp
+ *     → https://8ok.uk/a/5/v/<sha16>-lg.webp?exp=…&sig=…
+ *
+ * Accepts a URL that is already under `/a/` and re-signs it, so calling twice
+ * is not an error and does not produce `/a/a/`.
+ */
+declare function signAccessUrl(publicUrl: string, signingKey: string, opts: SignAccessOptions): Promise<string>;
+/** What every URL builder accepts so it can refuse a doomed URL. */
+type VisibilityHint = {
+    visibility?: "public" | "private";
+};
+/**
+ * Refuse to build a public URL for a private asset.
+ *
+ * Doctrine of the house: **a silence reads as "you can't"**. Returning
+ * `https://8ok.uk/5/v/<sha>-lg.webp` for a private asset is not a smaller
+ * failure than throwing — it is a URL that answers 404, in a platform where a
+ * 404 has always meant "that file does not exist". The caller then debugs the
+ * wrong thing.
+ *
+ * Only refuses when it was actually TOLD. A caller passing `{ sha }` carries no
+ * visibility, and guessing would break every existing call site to protect
+ * assets that are not there.
+ */
+declare function assertPublic(asset: VisibilityHint, fn: string, 
+/**
+ * The call to make instead — declared per call site, not guessed.
+ *
+ * It matters which one: `getPrivateAssetUrl` signs a STORED preset, and
+ * pointing a transform caller at it sends them to a function that cannot do
+ * what they asked for. The first version of this message named
+ * `getPrivateAssetUrl` for all seven builders; a test caught it.
+ */
+escape: string): void;
+/**
+ * Refuse a value whose `sha` is missing or malformed, instead of interpolating
+ * it into a URL.
+ *
+ * ## Found by a Haiku agent, 2026-08-23
+ *
+ * It did the most natural thing there is — passed the result of `upload()`
+ * straight to `transform()` — and got:
+ *
+ *     https://8ok.uk/t/width=1280/undefined.webp
+ *
+ * `UploadResult` carries `sha256`; every URL builder wants `sha`. TypeScript
+ * catches the mismatch, but an agent running through `bun` (or anyone in plain
+ * JS) sees no error at all: just a 200-shaped URL with the word `undefined` in
+ * it, which 404s later and somewhere else.
+ *
+ * The house rule applies exactly as it does to private assets: **a silence
+ * reads as "you can't"**. A builder that cannot name the asset must say so at
+ * the call site, not hand back a string that will fail far from here.
+ */
+declare function assertSha(asset: {
+    sha?: unknown;
+}, fn: string): void;
+
 /**
  * Color palette helpers — render harmonious ambient backgrounds behind
  * product images, inspired by Spotify Now Playing / Apple Music / Pico.
@@ -92,83 +203,6 @@ declare function iteratePaletteSwatches(palette: AssetPalette | null | undefined
  */
 declare function getPaletteBlurBackground(palette: AssetPalette | null | undefined): string | undefined;
 
-/**
- * @nitida/asset-client/slots — slot resolver for tenant-named assets.
- *
- * Slots give tenants a way to attach stable, human-readable names
- * ("webapp.wizard.pool-type.icon-1", "storefront.cr.hero-video.landscape_hd_16x9.mp4")
- * to assets they uploaded. Consumers resolve names → AssetDTOs at
- * build / runtime so their source never hardcodes a CDN URL; an
- * admin rebinds a slot in the platform console and every consumer
- * picks up the swap on cache refresh.
- *
- * Two layers in this package:
- *   - `resolveSlot` / `resolveSlots` — universal (server, edge,
- *     workers) fetch helpers. Cache 60s by default.
- *   - React hooks live in `@nitida/asset-client/react/use-slot`
- *     (kept out of this module so the SSR-safe core stays
- *     dependency-free of react).
- */
-
-type SlotDTO = {
-    slotKey: string;
-    /** Preset hint set when the slot was bound (e.g. `thumb` for icon slots). */
-    preset: VariantPreset | null;
-    description: string | null;
-    updatedAt: string;
-    asset: AssetDTO;
-};
-type SlotResolution = {
-    /** The resolved DTO (`null` when the slot is unbound or asset missing). */
-    slot: SlotDTO | null;
-    /**
-     * Effective preset — what `url` below was built with. Resolution order:
-     *   1. caller's `preset` override
-     *   2. slot's `preset` hint
-     *   3. `lg` for images, `video` for video kind
-     */
-    preset: VariantPreset;
-    /** The CDN URL the consumer should use. */
-    url: string | null;
-};
-/**
- * Configure the resolver process-wide. Call once at boot from your
- * storefront layout / server entry / worker init.
- *
- *   configureSlotResolver({
- *     endpoint: process.env.AQUIENPZ_URL,
- *     apiKey:   process.env.AQUIENPZ_API_KEY,   // amk_rt_* — server-only
- *     tenantCode: "acme-co",
- *   });
- */
-declare function configureSlotResolver(opts: {
-    endpoint?: string;
-    apiKey?: string;
-    tenantCode?: string;
-}): void;
-/** Wipe the in-process cache (test helper or forced refresh). */
-declare function invalidateSlotCache(slotKey?: string): void;
-type ResolveSlotOptions = {
-    /** Override preset (caller knows the use case better than the slot binding). */
-    preset?: VariantPreset;
-    /** TTL for the in-process cache. Default 60s. Set 0 to bypass. */
-    ttlMs?: number;
-};
-/**
- * Resolve a single slot to a CDN URL. Returns `{slot: null, url: null}`
- * when the slot is unbound — callers fall back to a placeholder.
- *
- * Cached for `ttlMs` (default 60s). Slot rebindings propagate within the
- * TTL window without an app restart.
- */
-declare function resolveSlot(slotKey: string, opts?: ResolveSlotOptions): Promise<SlotResolution>;
-/**
- * Bulk-resolve N slot keys in one round-trip. The SDK's `useSlots`
- * React hook calls this so every storefront header (logo + tagline +
- * nav cover + …) loads as one request.
- */
-declare function resolveSlots(slotKeys: string[], opts?: ResolveSlotOptions): Promise<Record<string, SlotResolution>>;
-
 /**
  * On-the-fly transform URL builder.
  *
@@ -309,7 +343,7 @@ declare function serializeTransform(opts: SignedTransformOptions): string;
  *   <video src={aq.transformVideo(asset, { width: 1080, height: 1920 })}
  *          autoPlay muted loop playsInline />
  */
-declare function getVideoTransformUrl(asset: Pick<AssetDTO, "sha">, opts: TransformOptions): string | null;
+declare function getVideoTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: TransformOptions): string | null;
 /**
  * Build an HLS streaming URL for a VIDEO asset (Phase 5). Returns the
  * master.m3u8 entry point — HLS-aware players (Video.js's
@@ -368,8 +402,9 @@ declare function getVideoTransformUrl(asset: Pick<AssetDTO, "sha">, opts: Transf
  * on demand after the raw is unavailable it reads the `-v.mp4`, which is
  * capped at 1920 wide. `getAssetUrl(sha, "video")` is always <= 1080p.
  */
-declare function getHlsStreamingUrl(asset: Pick<AssetDTO, "sha">, opts?: Omit<TransformOptions, "format">): string;
-declare function getTransformUrl(asset: Pick<AssetDTO, "sha">, opts: TransformOptions): string | null;
+declare function getHlsStreamingUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts?: Omit<TransformOptions, "format">): string;
+
+declare function getTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: TransformOptions): string | null;
 /**
  * Build AND sign a transform URL, allowing an off-ladder custom `width`.
  *
@@ -381,7 +416,7 @@ declare function getTransformUrl(asset: Pick<AssetDTO, "sha">, opts: TransformOp
  * Returns `null` only when `opts` serialize to an empty DSL (no transform
  * requested) — same contract as {@link getTransformUrl}.
  */
-declare function getSignedTransformUrl(asset: Pick<AssetDTO, "sha">, opts: SignedTransformOptions, signingKey: string): Promise<string> | null;
+declare function getSignedTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: SignedTransformOptions, signingKey: string): Promise<string> | null;
 /**
  * Sign a transform URL with the tenant's HMAC signing key. Appends
  * `?sig=<hex>` where hex = HMAC-SHA256(signingKey, `<canonical-DSL>/<filename>`).
@@ -404,7 +439,84 @@ declare function signTransformUrl(unsignedUrl: string, signingKey: string): Prom
  *     sizes="(max-width: 768px) 100vw, 50vw"
  *   />
  */
-declare function getTransformSrcSet(asset: Pick<AssetDTO, "sha">, widths: number[], extraOpts?: Omit<TransformOptions, "width">): string;
+declare function getTransformSrcSet(asset: Pick<AssetDTO, "sha"> & VisibilityHint, widths: number[], extraOpts?: Omit<TransformOptions, "width">): string;
+
+/**
+ * @nitida/asset-client/slots — slot resolver for tenant-named assets.
+ *
+ * Slots give tenants a way to attach stable, human-readable names
+ * ("webapp.wizard.pool-type.icon-1", "storefront.cr.hero-video.landscape_hd_16x9.mp4")
+ * to assets they uploaded. Consumers resolve names → AssetDTOs at
+ * build / runtime so their source never hardcodes a CDN URL; an
+ * admin rebinds a slot in the platform console and every consumer
+ * picks up the swap on cache refresh.
+ *
+ * Two layers in this package:
+ *   - `resolveSlot` / `resolveSlots` — universal (server, edge,
+ *     workers) fetch helpers. Cache 60s by default.
+ *   - React hooks live in `@nitida/asset-client/react/use-slot`
+ *     (kept out of this module so the SSR-safe core stays
+ *     dependency-free of react).
+ */
+
+type SlotDTO = {
+    slotKey: string;
+    /** Preset hint set when the slot was bound (e.g. `thumb` for icon slots). */
+    preset: VariantPreset | null;
+    description: string | null;
+    updatedAt: string;
+    asset: AssetDTO;
+};
+type SlotResolution = {
+    /** The resolved DTO (`null` when the slot is unbound or asset missing). */
+    slot: SlotDTO | null;
+    /**
+     * Effective preset — what `url` below was built with. Resolution order:
+     *   1. caller's `preset` override
+     *   2. slot's `preset` hint
+     *   3. `lg` for images, `video` for video kind
+     */
+    preset: VariantPreset;
+    /** The CDN URL the consumer should use. */
+    url: string | null;
+};
+/**
+ * Configure the resolver process-wide. Call once at boot from your
+ * storefront layout / server entry / worker init.
+ *
+ *   configureSlotResolver({
+ *     endpoint: process.env.AQUIENPZ_URL,
+ *     apiKey:   process.env.AQUIENPZ_API_KEY,   // amk_rt_* — server-only
+ *     tenantCode: "acme-co",
+ *   });
+ */
+declare function configureSlotResolver(opts: {
+    endpoint?: string;
+    apiKey?: string;
+    tenantCode?: string;
+}): void;
+/** Wipe the in-process cache (test helper or forced refresh). */
+declare function invalidateSlotCache(slotKey?: string): void;
+type ResolveSlotOptions = {
+    /** Override preset (caller knows the use case better than the slot binding). */
+    preset?: VariantPreset;
+    /** TTL for the in-process cache. Default 60s. Set 0 to bypass. */
+    ttlMs?: number;
+};
+/**
+ * Resolve a single slot to a CDN URL. Returns `{slot: null, url: null}`
+ * when the slot is unbound — callers fall back to a placeholder.
+ *
+ * Cached for `ttlMs` (default 60s). Slot rebindings propagate within the
+ * TTL window without an app restart.
+ */
+declare function resolveSlot(slotKey: string, opts?: ResolveSlotOptions): Promise<SlotResolution>;
+/**
+ * Bulk-resolve N slot keys in one round-trip. The SDK's `useSlots`
+ * React hook calls this so every storefront header (logo + tagline +
+ * nav cover + …) loads as one request.
+ */
+declare function resolveSlots(slotKeys: string[], opts?: ResolveSlotOptions): Promise<Record<string, SlotResolution>>;
 
 /**
  * @nitida/asset-client — read helpers for asset URLs.
@@ -626,6 +738,23 @@ type AssetDTO = {
      */
     presets: string;
     status: "processing" | "ready" | "failed";
+    /**
+     * Who may fetch the bytes.
+     *
+     *   - `"public"` — the CDN serves it to anyone with the URL. The default,
+     *     and what all 27 484 assets were until this field existed.
+     *   - `"private"` — every public door answers **404**: the stored variants,
+     *     the raw original, the HLS ladder and `/t/`. The bytes are reachable
+     *     only through a signed URL under `/a/{tenant}/…?exp&sig`, which your
+     *     BACKEND mints with {@link getPrivateAssetUrl}.
+     *
+     * Optional so an older server that does not send it is read as `"public"` —
+     * which is what such a server means.
+     *
+     * ⚠️ A 404 on a private asset is not a missing file. It is the feature
+     * working. See {@link getPrivateAssetUrl}.
+     */
+    visibility?: "public" | "private";
     /** Soft-delete timestamp (ISO). Hidden from catalog when set. */
     deletedAt?: string | null;
     /**
@@ -695,7 +824,59 @@ type OriginalHints = {
  * const url = hasPreset(asset, "thumb") ? getAssetUrl(asset, "thumb") : null;
  * ```
  */
-declare function getAssetUrl(asset: Pick<AssetDTO, "sha"> & OriginalHints, preset: VariantPreset): string;
+declare function getAssetUrl(asset: Pick<AssetDTO, "sha"> & OriginalHints & VisibilityHint, preset: VariantPreset): string;
+/**
+ * The signed URL for one preset of a PRIVATE asset — what every refusal above
+ * points at.
+ *
+ * ```ts
+ * // On your BACKEND, once you have decided this viewer may see it:
+ * const url = await getPrivateAssetUrl(asset, "lg", tenantSigningKey, {
+ *   expiresInSeconds: 300,
+ * });
+ * ```
+ *
+ * It works on a public asset too — `/a/` is a different door onto the same
+ * object — but there is no reason to pay for it: a public URL is cacheable at
+ * the edge and costs nothing, a signed one is neither.
+ *
+ * ⚠️ **Backend only.** Handing the signing key to a browser lets any visitor
+ * mint URLs for every private asset the tenant owns, which is the whole
+ * property the private tree exists to provide.
+ *
+ * ⚠️ Needs {@link setTenantId} (or a `NitidaClient` with `tenantId`), like
+ * every variant URL builder: the tenant segment is base36 and part of what the
+ * signature covers, so a missing tenant does not produce a wrong URL — it
+ * produces an unsignable one.
+ */
+declare function getPrivateAssetUrl(asset: Pick<AssetDTO, "sha"> & OriginalHints, preset: VariantPreset, signingKey: string, opts: SignAccessOptions): Promise<string>;
+/**
+ * The signed URL for a TRANSFORM of a private asset — an arbitrary width, crop
+ * or format, not just the sizes that happen to be materialised.
+ *
+ * ```ts
+ * const url = await getPrivateTransformUrl(
+ *   asset,
+ *   { width: 1280, format: "webp" },
+ *   tenantSigningKey,
+ *   { expiresInSeconds: 300 },
+ * );
+ * // → https://8ok.uk/a/5/t/format=webp,width=1280/<sha>.webp?exp=…&sig=…
+ * ```
+ *
+ * Why this exists at all: a private asset that can only be served at the sizes
+ * someone already generated is barely a product. The signed tree mirrors the
+ * public one, transforms included.
+ *
+ * Returns `null` when `opts` serialize to an empty DSL — same contract as
+ * {@link getTransformUrl}, because "no transform requested" is not an error,
+ * it just means you wanted {@link getPrivateAssetUrl}.
+ *
+ * ⚠️ **Backend only**, like every signer here. And note the width is a plain
+ * `number`: a signed URL is a trusted caller, so the edge ladder does not
+ * apply — the same rule `getSignedTransformUrl` already follows.
+ */
+declare function getPrivateTransformUrl(asset: Pick<AssetDTO, "sha">, opts: SignedTransformOptions, signingKey: string, signOpts: SignAccessOptions): Promise<string | null>;
 /**
  * Did the processor actually generate this preset?
  *
@@ -714,7 +895,7 @@ declare function getAssetUrl(asset: Pick<AssetDTO, "sha"> & OriginalHints, prese
  * ```
  */
 declare function hasPreset(asset: Pick<AssetDTO, "presets">, preset: VariantPreset): boolean;
-declare function getAssetSrcSet(asset: Pick<AssetDTO, "sha" | "presets">): string;
+declare function getAssetSrcSet(asset: Pick<AssetDTO, "sha" | "presets"> & VisibilityHint): string;
 /**
  * Compute the dimensions a variant would have given the source asset's
  * width/height and the variant's bounding box. For thumbnails (square
@@ -731,4 +912,4 @@ declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
     height: number;
 } | null;
 
-export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type RequestablePreset, type ResolveSlotOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signTransformUrl };
+export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl };