<SYSTEM>This is the full developer documentation for nitida</SYSTEM>

# nitida

> Hand it raw media. Get back every size, every format, every screen — crisp.

Upload that survives a phone

Multipart with resume across a reload, IndexedDB-backed, progress per file. A dropped 4G connection resumes where it stopped instead of starting over.

Compression in the browser

A worker and `OffscreenCanvas` — the main thread never blocks. HEIC decodes natively where the engine can (**136 ms**), and only falls back to WASM where it cannot, so the 341 KB decoder stays unfetched for most users.

Video, not just images

Poster, transcode, an adaptive HLS ladder, and a cheap proxy built for machine analysis rather than for eyes.

Multi-tenant from the first line

Keys per tenant, isolation by prefix, and usage you can actually read. Running in production across five tenants.

## Two packages, one idea

[Section titled “Two packages, one idea”](#two-packages-one-idea)

**`@aquienpz/asset-client`** builds URLs. No network, no key, nothing to configure beyond a tenant id. If all your app does is *render* media, this is the only thing you need.

**`@aquienpz/sdk`** adds the write half — upload, compress, register, poll — and re-exports every URL builder, so you never import both for the same job.

## The reference is generated from the types

[Section titled “The reference is generated from the types”](#the-reference-is-generated-from-the-types)

Every page under **API reference** is produced from the source on each build. Nothing there is transcribed by hand, which is the only way a reference stays true after a rename. The same content is published at [`/llms.txt`](/llms.txt) and [`/llms-full.txt`](/llms-full.txt) so an agent can read the whole surface in one fetch.

# Exclude

```ts
type Exclude<T, U> = T extends U ? never : T;
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1618

Exclude from T those types that are assignable to U

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `T`            |
| `U`            |

# Omit

```ts
type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1628

Construct a type with the properties of T except for those in type K.

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter            |
| ------------------------- |
| `T`                       |
| `K` *extends* keyof `any` |

# computeVariantDimensions

```ts
function computeVariantDimensions(asset, preset):
  | {
  height: number;
  width: number;
}
  | null;
```

Defined in: packages/asset-client/src/index.ts:353

Compute the dimensions a variant would have given the source asset’s width/height and the variant’s bounding box. For thumbnails (square smart-crop) the result is always 256×256; for the other presets, scales the max side to the box dimension and the other side proportionally.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                                                                   |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"w"` \| `"h"`> |
| `preset`  | [`VariantPreset`](/api/asset-client/src/type-aliases/variantpreset/)                                                                   |

## Returns

[Section titled “Returns”](#returns)

\| { `height`: `number`; `width`: `number`; } | `null`

# configureSlotResolver

```ts
function configureSlotResolver(opts): void;
```

Defined in: packages/asset-client/src/slots.ts:70

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.ASSET\_MANAGER\_RUNTIME\_KEY, tenantCode: “realtyone-cr”, });

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter          | Type                                                                     |
| ------------------ | ------------------------------------------------------------------------ |
| `opts`             | { `apiKey?`: `string`; `endpoint?`: `string`; `tenantCode?`: `string`; } |
| `opts.apiKey?`     | `string`                                                                 |
| `opts.endpoint?`   | `string`                                                                 |
| `opts.tenantCode?` | `string`                                                                 |

## Returns

[Section titled “Returns”](#returns)

`void`

# extractAssetSha

```ts
function extractAssetSha(url): string | null;
```

Defined in: packages/asset-client/src/transform.ts:160

Extract the 16-hex short sha from an aquienpz CDN URL, regardless of shape:

* tenant-prefixed variant: `https://8ok.uk/4/v/<sha16>-<preset>.<ext>`
* legacy variant: `https://8ok.uk/<sha16>-<preset>.<ext>`
* on-the-fly transform: `https://8ok.uk/t/<dsl>/<sha16>.<ext>`
* streaming HLS: `https://8ok.uk/t/format=hls/<sha16>.m3u8`

Returns `null` for non-aquienpz URLs (pexels, googleusercontent, raw uploaded URLs to other CDNs) so call sites can fall back to the URL with a plain `<img>` instead of generating a broken transform URL.

Useful when a value reaches the component as a pre-built URL string (legacy data, site-config JSON, third-party feeds) but you want to drop in `getTransformSrcSet` for the responsive ladder if it happens to be an aquienpz asset.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                              |
| --------- | --------------------------------- |
| `url`     | `string` \| `null` \| `undefined` |

## Returns

[Section titled “Returns”](#returns)

`string` | `null`

# getAmbientGradient

```ts
function getAmbientGradient(palette, opts?): string | undefined;
```

Defined in: packages/asset-client/src/palette.ts:63

Build a CSS linear-gradient from the palette. Useful for hero / detail backgrounds.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter     | Type                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `palette`     | \| [`AssetPalette`](/api/asset-client/src/type-aliases/assetpalette/) \| `null` \| `undefined` |
| `opts`        | { `angle?`: `string`; `from?`: keyof AssetPalette; `to?`: keyof AssetPalette; }                |
| `opts.angle?` | `string`                                                                                       |
| `opts.from?`  | keyof AssetPalette                                                                             |
| `opts.to?`    | keyof AssetPalette                                                                             |

## Returns

[Section titled “Returns”](#returns)

`string` | `undefined`

# getAssetDimensions

```ts
function getAssetDimensions(asset):
  | {
  height: number;
  width: number;
}
  | null;
```

Defined in: packages/asset-client/src/index.ts:369

Source dimensions, for aspect-ratio sizing.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                                                                   |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"w"` \| `"h"`> |

## Returns

[Section titled “Returns”](#returns)

\| { `height`: `number`; `width`: `number`; } | `null`

# getAssetSrcSet

```ts
function getAssetSrcSet(asset): string;
```

Defined in: packages/asset-client/src/index.ts:337

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                                                                           |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"sha"` \| `"presets"`> |

## Returns

[Section titled “Returns”](#returns)

`string`

# getAssetUrl

```ts
function getAssetUrl(asset, preset): string;
```

Defined in: packages/asset-client/src/index.ts:290

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.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                                                                                     |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"sha"`> & { `mime?`: `string`; } |
| `preset`  | [`VariantPreset`](/api/asset-client/src/type-aliases/variantpreset/)                                                                                     |

## Returns

[Section titled “Returns”](#returns)

`string`

## Examples

[Section titled “Examples”](#examples)

**Video — the tenant segment is base36, so let this build the path**

```ts
import { getAssetUrl, setTenantId } from "@aquienpz/asset-client";


setTenantId(12);                        // 12 → "c"; a decimal "/12/v/" 404s
getAssetUrl({ sha }, "video");          // → https://8ok.uk/c/v/<sha16>-v.mp4
getAssetUrl({ sha }, "poster");         // → https://8ok.uk/c/v/<sha16>-p.webp
```

**The \`original\`, which needs the mime — and still deserves a HEAD**

```ts
getAssetUrl({ sha }, "original");             // → …-o.bin   ❌ 404, always
getAssetUrl({ sha, mime }, "original");       // → …-o.webp  ✓


// ⚠️ 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" });
```

**Check before you link**

```ts
import { getAssetUrl, hasPreset } from "@aquienpz/asset-client";
const url = hasPreset(asset, "thumb") ? getAssetUrl(asset, "thumb") : null;
```

# getCdnBase

```ts
function getCdnBase(): string;
```

Defined in: packages/asset-client/src/index.ts:192

## Returns

[Section titled “Returns”](#returns)

`string`

# getHlsStreamingUrl

```ts
function getHlsStreamingUrl(asset, opts?): string;
```

Defined in: packages/asset-client/src/transform.ts:284

Build an HLS streaming URL for a VIDEO asset (Phase 5). Returns the master.m3u8 entry point — HLS-aware players (Video.js’s @videojs/http-streaming, hls.js, native iOS Safari) follow it to fetch the variant playlist + segments at the appropriate bitrate for the connection.

⚠️ A master.m3u8 is NOT a video file. Assigning it to `<video src>` works only where the engine has native HLS; everywhere else it needs an MSE player. And the classic feature test is now WRONG: Chrome 147 (April 2026) added native HLS, so `canPlayType("application/vnd.apple.mpegurl")` answers “maybe” there and routes Chrome to the native branch, where it opened a measured 17 s hero at 426x240 for \~8 s. Branch on the ENGINE:

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"sha"`>                       |
| `opts`    | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<[`TransformOptions`](/api/asset-client/src/type-aliases/transformoptions/), `"format"`> |

## Returns

[Section titled “Returns”](#returns)

`string`

## Example

[Section titled “Example”](#example)

```ts
function prefersNativeHls(video: HTMLVideoElement): boolean {
  if (video.canPlayType("application/vnd.apple.mpegurl") === "") return false;
  // Apple's engine, or an engine with no MSE to fall back on (iOS < 17.1).
  return "ManagedMediaSource" in globalThis || !("MediaSource" in globalThis);
}


const src = getHlsStreamingUrl(asset);
if (prefersNativeHls(video)) {
  video.src = src;
} else {
  // Defaults open at a fixed low rung — measure instead of guessing.
  const hls = new Hls({ startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 });
  hls.loadSource(src);
  hls.attachMedia(video);
}
```

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); subsequent requests get 302 to the cached master.m3u8. Keep the progressive MP4 as a fallback source for that window.

The ladder’s ceiling is the source the job probes: built at ingest it reads the RAW upload and a 4K master yields 1440p/2160p rungs; rebuilt on demand after the raw is unavailable it reads the `-v.mp4`, which is capped at 1920 wide. `getAssetUrl(sha, "video")` is always <= 1080p.

# getPaletteBlurBackground

```ts
function getPaletteBlurBackground(palette): string | undefined;
```

Defined in: packages/asset-client/src/palette.ts:157

Build a multi-radial-gradient CSS `background` string from the palette swatches. Acts as a zero-extra-bytes alternative to the WebP LQIP: the palette is already in the DTO, so this placeholder costs nothing extra to ship. Renders as a smooth abstract “color cloud” reminiscent of the source image’s vibe.

Strategy: anchor 4 radial gradients at fixed corners using vibrant/muted pairs, layered over the dominant fill. Skips missing swatches gracefully.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                           |
| --------- | ---------------------------------------------------------------------------------------------- |
| `palette` | \| [`AssetPalette`](/api/asset-client/src/type-aliases/assetpalette/) \| `null` \| `undefined` |

## Returns

[Section titled “Returns”](#returns)

`string` | `undefined`

# getPaletteCssVars

```ts
function getPaletteCssVars(palette): Record<string, string>;
```

Defined in: packages/asset-client/src/palette.ts:104

CSS variables for a wrapper so a subtree can read –asset-bg / –asset-fg / –asset-dominant / –asset-vibrant / etc.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                           |
| --------- | ---------------------------------------------------------------------------------------------- |
| `palette` | \| [`AssetPalette`](/api/asset-client/src/type-aliases/assetpalette/) \| `null` \| `undefined` |

## Returns

[Section titled “Returns”](#returns)

[`Record`](/api/sdk/src/web/-internal-/type-aliases/record/)<`string`, `string`>

# getSignedTransformUrl

```ts
function getSignedTransformUrl(
   asset,
   opts,
   signingKey): Promise<string> | null;
```

Defined in: packages/asset-client/src/transform.ts:327

Build AND sign a transform URL, allowing an off-ladder custom `width`.

This is the escape hatch for [SignedTransformOptions](/api/asset-client/src/type-aliases/signedtransformoptions/): off-ladder widths only pass the edge whitelist when the URL is signed, so building one and signing it must happen together. For on-ladder widths prefer the plain [getTransformUrl](/api/asset-client/src/functions/gettransformurl/) (+ [signTransformUrl](/api/asset-client/src/functions/signtransformurl/) if you need a signature).

Returns `null` only when `opts` serialize to an empty DSL (no transform requested) — same contract as [getTransformUrl](/api/asset-client/src/functions/gettransformurl/).

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter    | Type                                                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `asset`      | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"sha"`> |
| `opts`       | [`SignedTransformOptions`](/api/asset-client/src/type-aliases/signedtransformoptions/)                                          |
| `signingKey` | `string`                                                                                                                        |

## Returns

[Section titled “Returns”](#returns)

`Promise`<`string`> | `null`

# getTenantId

```ts
function getTenantId(): number | null;
```

Defined in: packages/asset-client/src/index.ts:214

## Returns

[Section titled “Returns”](#returns)

`number` | `null`

# getTextColorForBackground

```ts
function getTextColorForBackground(swatch): string;
```

Defined in: packages/asset-client/src/palette.ts:80

Recommended text color (#000 or #FFF) for any background hex, computed via WCAG relative luminance.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                                         |
| --------- | ------------------------------------------------------------------------------------------------------------ |
| `swatch`  | \| `string` \| [`PaletteSwatch`](/api/asset-client/src/type-aliases/paletteswatch/) \| `null` \| `undefined` |

## Returns

[Section titled “Returns”](#returns)

`string`

# getTransformSrcSet

```ts
function getTransformSrcSet(
   asset,
   widths,
   extraOpts?): string;
```

Defined in: packages/asset-client/src/transform.ts:394

Build a responsive `srcSet` string by generating one transform URL per width. All other options apply to every URL.

\<img src={aq.transform(asset, { width: 800 })!} srcSet={aq.transformSrcSet(asset, \[320, 640, 960, 1280])} sizes=“(max-width: 768px) 100vw, 50vw” />

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter   | Type                                                                                                                                                 |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`     | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"sha"`>                      |
| `widths`    | `number`\[]                                                                                                                                          |
| `extraOpts` | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<[`TransformOptions`](/api/asset-client/src/type-aliases/transformoptions/), `"width"`> |

## Returns

[Section titled “Returns”](#returns)

`string`

# getTransformUrl

```ts
function getTransformUrl(asset, opts): string | null;
```

Defined in: packages/asset-client/src/transform.ts:309

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"sha"`> |
| `opts`    | [`TransformOptions`](/api/asset-client/src/type-aliases/transformoptions/)                                                      |

## Returns

[Section titled “Returns”](#returns)

`string` | `null`

# getVideoTransformUrl

```ts
function getVideoTransformUrl(asset, opts): string | null;
```

Defined in: packages/asset-client/src/transform.ts:231

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.

\<video src={aq.transformVideo(asset, { width: 1080, height: 1920 })} autoPlay muted loop playsInline />

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"sha"`> |
| `opts`    | [`TransformOptions`](/api/asset-client/src/type-aliases/transformoptions/)                                                      |

## Returns

[Section titled “Returns”](#returns)

`string` | `null`

# hasPreset

```ts
function hasPreset(asset, preset): boolean;
```

Defined in: packages/asset-client/src/index.ts:315

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.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                                                                |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/asset-client/src/type-aliases/assetdto/), `"presets"`> |
| `preset`  | [`VariantPreset`](/api/asset-client/src/type-aliases/variantpreset/)                                                                |

## Returns

[Section titled “Returns”](#returns)

`boolean`

## Example

[Section titled “Example”](#example)

```ts
import { hasPreset } from "@aquienpz/asset-client";


hasPreset({ presets: "oq" }, "original");  // → true   ("o" = original, "q" = thumb)
hasPreset({ presets: "oq" }, "lg");        // → false  — do not link to it
hasPreset({ presets: "pv" }, "aiproxy");   // → false  — video without the AI proxy
```

# invalidateSlotCache

```ts
function invalidateSlotCache(slotKey?): void;
```

Defined in: packages/asset-client/src/slots.ts:77

Wipe the in-process cache (test helper or forced refresh).

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter  | Type     |
| ---------- | -------- |
| `slotKey?` | `string` |

## Returns

[Section titled “Returns”](#returns)

`void`

# iteratePaletteSwatches

```ts
function iteratePaletteSwatches(palette): {
  hex: string;
  key: keyof AssetPalette;
  label: string;
}[];
```

Defined in: packages/asset-client/src/palette.ts:126

Iterate the palette in display order (dominant first, then vibrant + muted families). Useful for rendering a swatch strip in admin UIs.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                           |
| --------- | ---------------------------------------------------------------------------------------------- |
| `palette` | \| [`AssetPalette`](/api/asset-client/src/type-aliases/assetpalette/) \| `null` \| `undefined` |

## Returns

[Section titled “Returns”](#returns)

{ `hex`: `string`; `key`: keyof [`AssetPalette`](/api/asset-client/src/type-aliases/assetpalette/); `label`: `string`; }\[]

# pickAmbientBackground

```ts
function pickAmbientBackground(palette):
  | PaletteSwatch
  | null;
```

Defined in: packages/asset-client/src/palette.ts:51

Pick the swatch best suited for an ambient surface behind the image. Prefers muted/light tones — too vibrant a background fights the image.

Order: lightMuted → muted → lightVibrant → dominant.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                           |
| --------- | ---------------------------------------------------------------------------------------------- |
| `palette` | \| [`AssetPalette`](/api/asset-client/src/type-aliases/assetpalette/) \| `null` \| `undefined` |

## Returns

[Section titled “Returns”](#returns)

\| [`PaletteSwatch`](/api/asset-client/src/type-aliases/paletteswatch/) | `null`

# resolveSlot

```ts
function resolveSlot(slotKey, opts?): Promise<SlotResolution>;
```

Defined in: packages/asset-client/src/slots.ts:132

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.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                           |
| --------- | ------------------------------------------------------------------------------ |
| `slotKey` | `string`                                                                       |
| `opts`    | [`ResolveSlotOptions`](/api/asset-client/src/type-aliases/resolveslotoptions/) |

## Returns

[Section titled “Returns”](#returns)

`Promise`<[`SlotResolution`](/api/asset-client/src/type-aliases/slotresolution/)>

# resolveSlots

```ts
function resolveSlots(slotKeys, opts?): Promise<Record<string, SlotResolution>>;
```

Defined in: packages/asset-client/src/slots.ts:152

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.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter  | Type                                                                           |
| ---------- | ------------------------------------------------------------------------------ |
| `slotKeys` | `string`\[]                                                                    |
| `opts`     | [`ResolveSlotOptions`](/api/asset-client/src/type-aliases/resolveslotoptions/) |

## Returns

[Section titled “Returns”](#returns)

`Promise`<[`Record`](/api/sdk/src/web/-internal-/type-aliases/record/)<`string`, [`SlotResolution`](/api/asset-client/src/type-aliases/slotresolution/)>>

# serializeTransform

```ts
function serializeTransform(opts): string;
```

Defined in: packages/asset-client/src/transform.ts:169

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                                   |
| --------- | -------------------------------------------------------------------------------------- |
| `opts`    | [`SignedTransformOptions`](/api/asset-client/src/type-aliases/signedtransformoptions/) |

## Returns

[Section titled “Returns”](#returns)

`string`

# setCdnBase

```ts
function setCdnBase(url): void;
```

Defined in: packages/asset-client/src/index.ts:189

Override the CDN base for the entire process (e.g. in tests, or when pointing at a tenant-specific CDN). Storefront layouts call this once at boot.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type     |
| --------- | -------- |
| `url`     | `string` |

## Returns

[Section titled “Returns”](#returns)

`void`

# setTenantId

```ts
function setTenantId(id): void;
```

Defined in: packages/asset-client/src/index.ts:210

Set the process-global tenant id used to build tenant-prefixed CDN URLs.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                              |
| --------- | --------------------------------- |
| `id`      | `number` \| `null` \| `undefined` |

## Returns

[Section titled “Returns”](#returns)

`void`

# signTransformUrl

```ts
function signTransformUrl(unsignedUrl, signingKey): Promise<string>;
```

Defined in: packages/asset-client/src/transform.ts:348

Sign a transform URL with the tenant’s HMAC signing key. Appends `?sig=<hex>` where hex = HMAC-SHA256(signingKey, `<canonical-DSL>/<filename>`).

Must agree byte-for-byte with the server’s `verifyTransformSignature`. Uses WebCrypto, so works in browsers, Node ≥ 16, Bun, and Workers.

The canonical DSL is the one already produced by `serializeTransform` (sort keys + lowercase strings), so signing a URL built by `getTransformUrl` is automatic — the same canonical form is in the URL path.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter     | Type     |
| ------------- | -------- |
| `unsignedUrl` | `string` |
| `signingKey`  | `string` |

## Returns

[Section titled “Returns”](#returns)

`Promise`<`string`>

# AssetDTO

```ts
type AssetDTO = {
  blur?: string | null;
  bytes: number;
  deletedAt?: string | null;
  dur?: number | null;
  h?: number | null;
  id: string;
  kind: "image" | "video" | "document" | "audio" | "other";
  mime: string;
  palette?:   | AssetPalette
     | null;
  presets: string;
  sha: string;
  status: "processing" | "ready" | "failed";
  variants?: AssetVariant[];
  w?: number | null;
};
```

Defined in: packages/asset-client/src/index.ts:131

Compact wire shape — what the server actually sends. Aliases (`w`, `h`, `dur`) are intentional to shave bytes per asset on dense lists.

## Properties

[Section titled “Properties”](#properties)

### blur?

[Section titled “blur?”](#blur)

```ts
optional blur?: string | null;
```

Defined in: packages/asset-client/src/index.ts:144

LQIP placeholder (data URL).

***

### bytes

[Section titled “bytes”](#bytes)

```ts
bytes: number;
```

Defined in: packages/asset-client/src/index.ts:137

***

### deletedAt?

[Section titled “deletedAt?”](#deletedat)

```ts
optional deletedAt?: string | null;
```

Defined in: packages/asset-client/src/index.ts:154

Soft-delete timestamp (ISO). Hidden from catalog when set.

***

### dur?

[Section titled “dur?”](#dur)

```ts
optional dur?: number | null;
```

Defined in: packages/asset-client/src/index.ts:142

Duration ms for videos.

***

### h?

[Section titled “h?”](#h)

```ts
optional h?: number | null;
```

Defined in: packages/asset-client/src/index.ts:140

***

### id

[Section titled “id”](#id)

```ts
id: string;
```

Defined in: packages/asset-client/src/index.ts:132

***

### kind

[Section titled “kind”](#kind)

```ts
kind: "image" | "video" | "document" | "audio" | "other";
```

Defined in: packages/asset-client/src/index.ts:135

***

### mime

[Section titled “mime”](#mime)

```ts
mime: string;
```

Defined in: packages/asset-client/src/index.ts:136

***

### palette?

[Section titled “palette?”](#palette)

```ts
optional palette?:
  | AssetPalette
  | null;
```

Defined in: packages/asset-client/src/index.ts:145

***

### presets

[Section titled “presets”](#presets)

```ts
presets: string;
```

Defined in: packages/asset-client/src/index.ts:151

Compact list of generated variants as their 1-char codes concatenated, e.g. “tcwh” (image) / “pv” (video without aiproxy). Ordered by ascending dimension.

***

### sha

[Section titled “sha”](#sha)

```ts
sha: string;
```

Defined in: packages/asset-client/src/index.ts:134

First 16 hex chars of sha256 — used to derive CDN URLs.

***

### status

[Section titled “status”](#status)

```ts
status: "processing" | "ready" | "failed";
```

Defined in: packages/asset-client/src/index.ts:152

***

### variants?

[Section titled “variants?”](#variants)

```ts
optional variants?: AssetVariant[];
```

Defined in: packages/asset-client/src/index.ts:160

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.

***

### w?

[Section titled “w?”](#w)

```ts
optional w?: number | null;
```

Defined in: packages/asset-client/src/index.ts:139

Source dims (for aspect-ratio calc on the client). Optional for non-images.

# AssetPalette

```ts
type AssetPalette = {
  d: string;
  dm?: string;
  dv?: string;
  lm?: string;
  lv?: string;
  m?: string;
  v?: string;
};
```

Defined in: packages/asset-client/src/palette.ts:16

Compact wire shape for an asset’s palette. All swatches optional except dominant.

## Properties

[Section titled “Properties”](#properties)

### d

[Section titled “d”](#d)

```ts
d: string;
```

Defined in: packages/asset-client/src/palette.ts:18

dominant hex (always present when palette exists)

***

### dm?

[Section titled “dm?”](#dm)

```ts
optional dm?: string;
```

Defined in: packages/asset-client/src/palette.ts:23

darkMuted

***

### dv?

[Section titled “dv?”](#dv)

```ts
optional dv?: string;
```

Defined in: packages/asset-client/src/palette.ts:21

darkVibrant

***

### lm?

[Section titled “lm?”](#lm)

```ts
optional lm?: string;
```

Defined in: packages/asset-client/src/palette.ts:24

lightMuted

***

### lv?

[Section titled “lv?”](#lv)

```ts
optional lv?: string;
```

Defined in: packages/asset-client/src/palette.ts:22

lightVibrant

***

### m?

[Section titled “m?”](#m)

```ts
optional m?: string;
```

Defined in: packages/asset-client/src/palette.ts:20

muted

***

### v?

[Section titled “v?”](#v)

```ts
optional v?: string;
```

Defined in: packages/asset-client/src/palette.ts:19

vibrant

# AssetVariant

```ts
type AssetVariant = {
  bytes: number;
  createdAt?: string;
  height?: number;
  preset: VariantPreset;
  sourceFrom?:   | VariantPreset
     | "upload";
  url: string;
  width?: number;
};
```

Defined in: packages/asset-client/src/index.ts:99

One generated variant of an asset. Returned by the admin endpoints (`GET /assets/:id`, `POST /assets/:id/regenerate`).

## Properties

[Section titled “Properties”](#properties)

### bytes

[Section titled “bytes”](#bytes)

```ts
bytes: number;
```

Defined in: packages/asset-client/src/index.ts:109

Byte size of the variant file on R2.

***

### createdAt?

[Section titled “createdAt?”](#createdat)

```ts
optional createdAt?: string;
```

Defined in: packages/asset-client/src/index.ts:124

ISO timestamp this variant was written. Absent on pre-trace variants.

***

### height?

[Section titled “height?”](#height)

```ts
optional height?: number;
```

Defined in: packages/asset-client/src/index.ts:107

Pixel height. Same caveat as `width`.

***

### preset

[Section titled “preset”](#preset)

```ts
preset: VariantPreset;
```

Defined in: packages/asset-client/src/index.ts:101

Long name (`thumb` / `sm` / … / `original`) — see [VariantPreset](/api/asset-client/src/type-aliases/variantpreset/).

***

### sourceFrom?

[Section titled “sourceFrom?”](#sourcefrom)

```ts
optional sourceFrom?:
  | VariantPreset
  | "upload";
```

Defined in: packages/asset-client/src/index.ts:122

Where the bytes for this variant came from. Useful for quality traceability — a `thumb` with `sourceFrom: "original"` is the canonical case, while `sourceFrom: "lg"` means it was derived from an already-encoded WebP (slight quality compounding).

* `"upload"` → first-write at `/assets/process`. The bytes came straight from the client’s PUT.
* `VariantPreset` → regenerated from that preset’s variant.

Absent on variants written before the trace field existed.

***

### url

[Section titled “url”](#url)

```ts
url: string;
```

Defined in: packages/asset-client/src/index.ts:103

Public CDN URL of this variant.

***

### width?

[Section titled “width?”](#width)

```ts
optional width?: number;
```

Defined in: packages/asset-client/src/index.ts:105

Pixel width. Absent for `original`-only assets where sharp was skipped, or for video presets.

# PaletteSwatch

```ts
type PaletteSwatch = {
  hex: string;
  textColor: "#000000" | "#FFFFFF";
};
```

Defined in: packages/asset-client/src/palette.ts:28

Backwards-compat alias for older callers that referenced PaletteSwatch.

## Properties

[Section titled “Properties”](#properties)

### hex

[Section titled “hex”](#hex)

```ts
hex: string;
```

Defined in: packages/asset-client/src/palette.ts:28

***

### textColor

[Section titled “textColor”](#textcolor)

```ts
textColor: "#000000" | "#FFFFFF";
```

Defined in: packages/asset-client/src/palette.ts:28

# ResolveSlotOptions

```ts
type ResolveSlotOptions = {
  preset?: VariantPreset;
  ttlMs?: number;
};
```

Defined in: packages/asset-client/src/slots.ts:118

## Properties

[Section titled “Properties”](#properties)

### preset?

[Section titled “preset?”](#preset)

```ts
optional preset?: VariantPreset;
```

Defined in: packages/asset-client/src/slots.ts:120

Override preset (caller knows the use case better than the slot binding).

***

### ttlMs?

[Section titled “ttlMs?”](#ttlms)

```ts
optional ttlMs?: number;
```

Defined in: packages/asset-client/src/slots.ts:122

TTL for the in-process cache. Default 60s. Set 0 to bypass.

# SignedTransformOptions

```ts
type SignedTransformOptions = Omit<TransformOptions, "width"> & {
  width?: number;
};
```

Defined in: packages/asset-client/src/transform.ts:130

Like [TransformOptions](/api/asset-client/src/type-aliases/transformoptions/) but with `width` widened to any `number` — 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 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 ([getSignedTransformUrl](/api/asset-client/src/functions/getsignedtransformurl/) / `aq.transform(asset, opts, { sign: true })`), never by the plain unsigned [getTransformUrl](/api/asset-client/src/functions/gettransformurl/).

## Type Declaration

[Section titled “Type Declaration”](#type-declaration)

### width?

[Section titled “width?”](#width)

```ts
optional width?: number;
```

Off-ladder width — valid ONLY on signed URLs (edge whitelist bypass).

# SlotDTO

```ts
type SlotDTO = {
  asset: AssetDTO;
  description: string | null;
  preset:   | VariantPreset
     | null;
  slotKey: string;
  updatedAt: string;
};
```

Defined in: packages/asset-client/src/slots.ts:26

## Properties

[Section titled “Properties”](#properties)

### asset

[Section titled “asset”](#asset)

```ts
asset: AssetDTO;
```

Defined in: packages/asset-client/src/slots.ts:32

***

### description

[Section titled “description”](#description)

```ts
description: string | null;
```

Defined in: packages/asset-client/src/slots.ts:30

***

### preset

[Section titled “preset”](#preset)

```ts
preset:
  | VariantPreset
  | null;
```

Defined in: packages/asset-client/src/slots.ts:29

Preset hint set when the slot was bound (e.g. `thumb` for icon slots).

***

### slotKey

[Section titled “slotKey”](#slotkey)

```ts
slotKey: string;
```

Defined in: packages/asset-client/src/slots.ts:27

***

### updatedAt

[Section titled “updatedAt”](#updatedat)

```ts
updatedAt: string;
```

Defined in: packages/asset-client/src/slots.ts:31

# SlotResolution

```ts
type SlotResolution = {
  preset: VariantPreset;
  slot: SlotDTO | null;
  url: string | null;
};
```

Defined in: packages/asset-client/src/slots.ts:35

## Properties

[Section titled “Properties”](#properties)

### preset

[Section titled “preset”](#preset)

```ts
preset: VariantPreset;
```

Defined in: packages/asset-client/src/slots.ts:44

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

***

### slot

[Section titled “slot”](#slot)

```ts
slot: SlotDTO | null;
```

Defined in: packages/asset-client/src/slots.ts:37

The resolved DTO (`null` when the slot is unbound or asset missing).

***

### url

[Section titled “url”](#url)

```ts
url: string | null;
```

Defined in: packages/asset-client/src/slots.ts:46

The CDN URL the consumer should use.

# TransformEffect

```ts
type TransformEffect = "removebg" | "genfill";
```

Defined in: packages/asset-client/src/transform.ts:65

# TransformFit

```ts
type TransformFit = "cover" | "contain" | "fill" | "inside" | "outside";
```

Defined in: packages/asset-client/src/transform.ts:43

# TransformFormat

```ts
type TransformFormat = "auto" | "avif" | "webp" | "jpeg" | "png" | "mp4" | "webm" | "hls";
```

Defined in: packages/asset-client/src/transform.ts:52

# TransformGravity

```ts
type TransformGravity = "auto" | "face" | "center" | "north" | "south" | "east" | "west";
```

Defined in: packages/asset-client/src/transform.ts:44

# TransformOptions

```ts
type TransformOptions = {
  dpr?: 1 | 2 | 3;
  duration?: number;
  effect?: TransformEffect;
  fit?: TransformFit;
  format?: TransformFormat;
  gravity?: TransformGravity;
  height?: number;
  quality?: "auto" | number;
  start?: number;
  width?: TransformWidth;
};
```

Defined in: packages/asset-client/src/transform.ts:67

## Properties

[Section titled “Properties”](#properties)

### dpr?

[Section titled “dpr?”](#dpr)

```ts
optional dpr?: 1 | 2 | 3;
```

Defined in: packages/asset-client/src/transform.ts:87

Device pixel ratio. Width/height are multiplied by this before resize.

***

### duration?

[Section titled “duration?”](#duration)

```ts
optional duration?: number;
```

Defined in: packages/asset-client/src/transform.ts:116

Video-only: clip duration in seconds (1..300). Image transforms ignore. With `start`, lets a single request grab a sub-clip.

***

### effect?

[Section titled “effect?”](#effect)

```ts
optional effect?: TransformEffect;
```

Defined in: packages/asset-client/src/transform.ts:106

AI effect applied before resize/encode.

* `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.

* `genfill`: aspect-extension outpaint via Flux-Fill Pro on Replicate. 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. Primary use case: building OG cards (1200×630) from portrait listing photos without awkward edge mirroring.

***

### fit?

[Section titled “fit?”](#fit)

```ts
optional fit?: TransformFit;
```

Defined in: packages/asset-client/src/transform.ts:79

Resize fit mode. Default `cover` server-side.

***

### format?

[Section titled “format?”](#format)

```ts
optional format?: TransformFormat;
```

Defined in: packages/asset-client/src/transform.ts:83

Output format. `auto` → policy decides (see asset-manager bench).

***

### gravity?

[Section titled “gravity?”](#gravity)

```ts
optional gravity?: TransformGravity;
```

Defined in: packages/asset-client/src/transform.ts:81

Crop gravity. `auto` uses sharp’s `attention` strategy.

***

### height?

[Section titled “height?”](#height)

```ts
optional height?: number;
```

Defined in: packages/asset-client/src/transform.ts:77

Target max-side height. Multiplied by `dpr` server-side.

***

### quality?

[Section titled “quality?”](#quality)

```ts
optional quality?: "auto" | number;
```

Defined in: packages/asset-client/src/transform.ts:85

Output quality. `auto` → format-specific default.

***

### start?

[Section titled “start?”](#start)

```ts
optional start?: number;
```

Defined in: packages/asset-client/src/transform.ts:111

Video-only: clip start in seconds. Image transforms ignore. Accepts decimals (e.g. 1.5 for sub-second seek).

***

### width?

[Section titled “width?”](#width)

```ts
optional width?: TransformWidth;
```

Defined in: packages/asset-client/src/transform.ts:75

Target max-side width in CSS pixels (multiplied by `dpr` server-side). MUST be a [TRANSFORM\_WIDTHS](/api/asset-client/src/variables/transform_widths/) value — off-ladder widths are rejected (HTTP 400) by the edge whitelist for unsigned URLs, so the type forbids them at compile time. For SIGNED URLs with a custom width, use [SignedTransformOptions](/api/asset-client/src/type-aliases/signedtransformoptions/) (which widens this to `number`).

# TransformWidth

```ts
type TransformWidth = typeof TRANSFORM_WIDTHS[number];
```

Defined in: packages/asset-client/src/transform.ts:41

A CDN-whitelisted transform width — the only widths `TransformOptions.width` accepts. Off-ladder widths are a compile error; for signed URLs that need a custom width, use [SignedTransformOptions](/api/asset-client/src/type-aliases/signedtransformoptions/) (number) via [getSignedTransformUrl](/api/asset-client/src/functions/getsignedtransformurl/) / `aq.transform(asset, opts, { sign: true })`.

# VariantPreset

```ts
type VariantPreset =
  | "thumb"
  | "sm"
  | "md"
  | "lg"
  | "xl"
  | "original"
  | "poster"
  | "video"
  | "aiproxy"
  | "mp3";
```

Defined in: packages/asset-client/src/index.ts:26

Image presets are size-based (Vercel `next/image` style):

* `thumb` is the only square crop — semantic icon use case
* `sm/md/lg` are max-side bounding boxes that preserve aspect ratio

Naming over the legacy `thumbnail/cover/web/hero` because the new names say what the variant IS (a size class) rather than what it might be USED for, removing the implicit landscape-only assumption that bit us with vertical product photos.

# PRESET_EXT

```ts
const PRESET_EXT: Record<VariantPreset, string>;
```

Defined in: packages/asset-client/src/index.ts:66

Variant extension by preset. Image variants are always WebP, video MP4.

# PRESET_LONG

```ts
const PRESET_LONG: Record<string, VariantPreset>;
```

Defined in: packages/asset-client/src/index.ts:61

# PRESET_MAX_DIM

```ts
const PRESET_MAX_DIM: Record<VariantPreset, number | null>;
```

Defined in: packages/asset-client/src/index.ts:80

Max-side dimension by preset; null for video / passthrough.

# PRESET_SHORT

```ts
const PRESET_SHORT: Record<VariantPreset, string>;
```

Defined in: packages/asset-client/src/index.ts:45

1-char alias used in R2 keys / wire `presets` string.

# TRANSFORM_WIDTHS

```ts
const TRANSFORM_WIDTHS: readonly [96, 128, 160, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840];
```

Defined in: packages/asset-client/src/transform.ts:31

Widths the CDN edge whitelists (DoS guard — see `apps/cdn-proxy` WHITELIST\_WIDTHS). 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.

# aquienpz

## Modules

[Section titled “Modules”](#modules)

* [asset-client/src](/api/asset-client/src/readme/)
* [sdk/src](/api/sdk/src/readme/)
* [sdk/src/expo](/api/sdk/src/expo/readme/)
* [sdk/src/native](/api/sdk/src/native/readme/)
* [sdk/src/react](/api/sdk/src/react/readme/)
* [sdk/src/server](/api/sdk/src/server/readme/)
* [sdk/src/web](/api/sdk/src/web/readme/)

# AquienpzClient

Defined in: packages/sdk/src/index.ts:1072

## Extended by

[Section titled “Extended by”](#extended-by)

* [`AquienpzClient`](/api/sdk/src/server/classes/aquienpzclient/)
* [`AquienpzClient`](/api/sdk/src/web/classes/aquienpzclient/)

## Constructors

[Section titled “Constructors”](#constructors)

### Constructor

[Section titled “Constructor”](#constructor)

```ts
new AquienpzClient(opts): AquienpzClient;
```

Defined in: packages/sdk/src/index.ts:1083

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                        |
| --------- | --------------------------------------------------------------------------- |
| `opts`    | [`AquienpzClientOptions`](/api/sdk/src/type-aliases/aquienpzclientoptions/) |

#### Returns

[Section titled “Returns”](#returns)

`AquienpzClient`

## Properties

[Section titled “Properties”](#properties)

### assets

[Section titled “assets”](#assets)

```ts
readonly assets: AssetsApi;
```

Defined in: packages/sdk/src/index.ts:1074

***

### opts

[Section titled “opts”](#opts)

```ts
readonly opts: AquienpzClientOptions;
```

Defined in: packages/sdk/src/index.ts:1081

Effective options — read-only. Exposed so the `/web` and `/expo` subpaths can inherit endpoint / apiKey / tenant scope from the configured client without re-passing them per call site.

***

### slots

[Section titled “slots”](#slots)

```ts
readonly slots: SlotsApi;
```

Defined in: packages/sdk/src/index.ts:1073

***

### usage

[Section titled “usage”](#usage)

```ts
readonly usage: UsageApi;
```

Defined in: packages/sdk/src/index.ts:1075

## Accessors

[Section titled “Accessors”](#accessors)

### tenantSegment

[Section titled “tenantSegment”](#tenantsegment)

#### Get Signature

[Section titled “Get Signature”](#get-signature)

```ts
get tenantSegment(): string;
```

Defined in: packages/sdk/src/index.ts:1102

Tenant id as base36 path segment (e.g. tenantId=4 → “4/v/”).

##### Returns

[Section titled “Returns”](#returns-1)

`string`

## Methods

[Section titled “Methods”](#methods)

### srcSetFor()

[Section titled “srcSetFor()”](#srcsetfor)

```ts
srcSetFor(asset): string;
```

Defined in: packages/sdk/src/index.ts:1112

Build a responsive srcSet across the available image presets.

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter | Type                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"` \| `"presets"`> |

#### Returns

[Section titled “Returns”](#returns-2)

`string`

***

### streamingUrl()

[Section titled “streamingUrl()”](#streamingurl)

```ts
streamingUrl(asset, opts?): string;
```

Defined in: packages/sdk/src/index.ts:1287

Build the HLS master playlist URL for a VIDEO asset (Phase 5).

Returns `<cdn>/t/format=hls(,start=…,duration=…)/<sha>.m3u8`. Pass to an HLS-aware player:

\<video src={aq.streamingUrl(asset)} controls playsInline // Video.js v10’s @videojs/http-streaming ships native HLS — // no plugin needed. />

On the first request the server returns **202 Accepted** while a Cloud Run Job builds the multi-rung ladder (typically 1-3 min for a 90 s source — five rungs of 240p/360p/480p/720p/1080p @ AAC). Subsequent requests hit the cache → **302** to the master.m3u8.

Supports `start` + `duration` to ladder a sub-clip. Other DSL params (width, height, fit) are ignored on the HLS path because the rungs determine resolution.

#### Parameters

[Section titled “Parameters”](#parameters-2)

| Parameter | Type                                                                                                                         |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`>       |
| `opts`    | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"format"`> |

#### Returns

[Section titled “Returns”](#returns-3)

`string`

***

### transform()

[Section titled “transform()”](#transform)

#### Call Signature

[Section titled “Call Signature”](#call-signature)

```ts
transform(asset, opts?): string;
```

Defined in: packages/sdk/src/index.ts:1145

Build an on-the-fly transform URL — `<cdn>/t/<dsl>/<sha>.<ext>`.

## URL CONVENTION — transforms are NOT tenant-prefixed (variants are)

[Section titled “URL CONVENTION — transforms are NOT tenant-prefixed (variants are)”](#url-convention--transforms-are-not-tenant-prefixed-variants-are)

Two distinct delivery paths, by design:

* **Variants / presets** (`urlFor`, `srcSetFor`, upload `cdnUrl`): `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>` ← tenant-scoped (e.g. `/4/v/<sha>-lg.webp`)
* **On-the-fly transforms** (`transform`, `transformSrcSet`): `<cdn>/t/<dsl>/<sha>.<ext>` ← GLOBAL, no tenant segment (`/t/...`) The transform service is content-addressed by sha + resizes from the source on demand, so it needs no tenant in the path. Prefixing a transform URL with `/<tenant>/t/...` 404s. Consumers that build URLs by hand must NOT add the tenant segment to `/t/` URLs.

Returns the canonical `lg` variant URL when called with empty options, so callers can swap `urlFor()` for `transform()` without thinking.

URLs with the same params in different order produce the same R2 cache entry (the server canonicalizes both sides). Safe to use as stable cache keys.

\<Image src={aq.transform(asset, { width: 1280 })} srcSet={aq.transformSrcSet(asset, \[640, 960, 1280, 1920])} sizes=“(max-width: 768px) 100vw, 50vw” />

##### Parameters

[Section titled “Parameters”](#parameters-3)

| Parameter | Type                                                                                                                   |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `opts?`   | `any`                                                                                                                  |

##### Returns

[Section titled “Returns”](#returns-4)

`string`

##### See

[Section titled “See”](#see)

[TransformOptions](/api/sdk/src/type-aliases/assetdto/) for the full param matrix.

#### Call Signature

[Section titled “Call Signature”](#call-signature-1)

```ts
transform(
   asset,
   opts,
signOpts): Promise<string>;
```

Defined in: packages/sdk/src/index.ts:1149

Build an on-the-fly transform URL — `<cdn>/t/<dsl>/<sha>.<ext>`.

## URL CONVENTION — transforms are NOT tenant-prefixed (variants are)

[Section titled “URL CONVENTION — transforms are NOT tenant-prefixed (variants are)”](#url-convention--transforms-are-not-tenant-prefixed-variants-are-1)

Two distinct delivery paths, by design:

* **Variants / presets** (`urlFor`, `srcSetFor`, upload `cdnUrl`): `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>` ← tenant-scoped (e.g. `/4/v/<sha>-lg.webp`)
* **On-the-fly transforms** (`transform`, `transformSrcSet`): `<cdn>/t/<dsl>/<sha>.<ext>` ← GLOBAL, no tenant segment (`/t/...`) The transform service is content-addressed by sha + resizes from the source on demand, so it needs no tenant in the path. Prefixing a transform URL with `/<tenant>/t/...` 404s. Consumers that build URLs by hand must NOT add the tenant segment to `/t/` URLs.

Returns the canonical `lg` variant URL when called with empty options, so callers can swap `urlFor()` for `transform()` without thinking.

URLs with the same params in different order produce the same R2 cache entry (the server canonicalizes both sides). Safe to use as stable cache keys.

\<Image src={aq.transform(asset, { width: 1280 })} srcSet={aq.transformSrcSet(asset, \[640, 960, 1280, 1920])} sizes=“(max-width: 768px) 100vw, 50vw” />

##### Parameters

[Section titled “Parameters”](#parameters-4)

| Parameter       | Type                                                                                                                   |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`         | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `opts`          | `SignedTransformOptions`                                                                                               |
| `signOpts`      | { `sign`: `true`; }                                                                                                    |
| `signOpts.sign` | `true`                                                                                                                 |

##### Returns

[Section titled “Returns”](#returns-5)

`Promise`<`string`>

##### See

[Section titled “See”](#see-1)

[TransformOptions](/api/sdk/src/type-aliases/assetdto/) for the full param matrix.

***

### transformSrcSet()

[Section titled “transformSrcSet()”](#transformsrcset)

#### Call Signature

[Section titled “Call Signature”](#call-signature-2)

```ts
transformSrcSet(
   asset,
   widths,
   extraOpts?): string;
```

Defined in: packages/sdk/src/index.ts:1189

Build a responsive `srcSet` string. One transform URL per width; all other options apply to every URL.

Pass `{ sign: true }` to return signed URLs (async). Without it, the call stays synchronous as before.

##### Parameters

[Section titled “Parameters”](#parameters-5)

| Parameter    | Type                                                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`      | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `widths`     | `number`\[]                                                                                                            |
| `extraOpts?` | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<`TransformOptions`, `"width"`>                           |

##### Returns

[Section titled “Returns”](#returns-6)

`string`

#### Call Signature

[Section titled “Call Signature”](#call-signature-3)

```ts
transformSrcSet(
   asset,
   widths,
   extraOpts,
signOpts): Promise<string>;
```

Defined in: packages/sdk/src/index.ts:1194

Build a responsive `srcSet` string. One transform URL per width; all other options apply to every URL.

Pass `{ sign: true }` to return signed URLs (async). Without it, the call stays synchronous as before.

##### Parameters

[Section titled “Parameters”](#parameters-6)

| Parameter       | Type                                                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `asset`         | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`>      |
| `widths`        | `number`\[]                                                                                                                 |
| `extraOpts`     | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"width"`> |
| `signOpts`      | { `sign`: `true`; }                                                                                                         |
| `signOpts.sign` | `true`                                                                                                                      |

##### Returns

[Section titled “Returns”](#returns-7)

`Promise`<`string`>

***

### transformVideo()

[Section titled “transformVideo()”](#transformvideo)

```ts
transformVideo(asset, opts?): string;
```

Defined in: packages/sdk/src/index.ts:1258

Build an on-the-fly VIDEO transform URL — Phase 4.

Same DSL shape as `transform()` but the URL has a `.mp4` (default) or `.webm` extension and the server routes the request to a Cloud Run Job for ffmpeg encoding (vs the inline sharp pipeline for images).

On the first request the route returns **202 Accepted** with `Retry-After: 10` while the Job 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.

const url = aq.transformVideo(asset, { width: 1080, height: 1920, fit: “cover”, start: 0, duration: 15, }); // Pass to Video.js / [; on the first load it // gets 202 + body.outputUrl; subsequent loads hit cache → 302.]({url})

Video-specific DSL params:

* `start` (seconds, decimal OK)
* `duration` (seconds, 1..300)
* `format`: “mp4” (default) or “webm”

The other params (`width`, `height`, `fit`) work identically to image transforms. `gravity`, `quality`, `effect`, `dpr` are accepted by the DSL but currently ignored on the video path.

#### Parameters

[Section titled “Parameters”](#parameters-7)

| Parameter | Type                                                                                                                   |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `opts`    | `TransformOptions`                                                                                                     |

#### Returns

[Section titled “Returns”](#returns-8)

`string`

***

### upload()

[Section titled “upload()”](#upload)

```ts
upload(input, opts?): Promise<UploadResult>;
```

Defined in: packages/sdk/src/index.ts:1348

Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-R2 PUT** → `/assets/process` → wait until the asset is ready.

⚠️ `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”.

#### Parameters

[Section titled “Parameters”](#parameters-8)

| Parameter | Type                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------- |
| `input`   | \| `File` \| `Blob` \| `Uint8Array`<[`ArrayBufferLike`](/api/sdk/src/web/-internal-/type-aliases/arraybufferlike/)> |
| `opts`    | [`UploadOptions`](/api/sdk/src/type-aliases/uploadoptions/)                                                         |

#### Returns

[Section titled “Returns”](#returns-9)

`Promise`<[`UploadResult`](/api/sdk/src/type-aliases/uploadresult/)>

#### Examples

[Section titled “Examples”](#examples)

**Deliver an image on a site (the responsive ladder)**

```ts
import { AquienpzClient } from "@aquienpz/sdk/server";


const aq = new AquienpzClient({ endpoint, apiKey, tenantCode, tenantId });
const { assetId, sha256 } = await aq.upload(file, {
  fileName: file.name,
  presets: ["thumb", "sm", "md", "lg"],
});
```

**ARCHIVE a file — you must ask for \`original\`**

```ts
await aq.upload(bytes, {
  fileName: "contrato.pdf",
  contentType: "application/pdf",
  presets: ["original"],          // without this the bytes are unrecoverable
});
```

**Raw bytes need an explicit MIME**

```ts
await aq.upload(bytes, { fileName: "track.mp3", contentType: "audio/mpeg" });
// Without either, it stores as kind:"other" — no variants, and regenerate() is unsupported.
```

**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.
await aq.upload(clip, { fileName: "tour.mp4", presets: ["poster", "video"] });


// Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost Job time
// and permanent R2 objects that nothing else reads.
```

***

### urlFor()

[Section titled “urlFor()”](#urlfor)

```ts
urlFor(asset, preset?): string;
```

Defined in: packages/sdk/src/index.ts:1107

Build the canonical CDN URL deterministically from sha + preset.

#### Parameters

[Section titled “Parameters”](#parameters-9)

| Parameter | Type                                                                                                                   | Default value |
| --------- | ---------------------------------------------------------------------------------------------------------------------- | ------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> | `undefined`   |
| `preset`  | `VariantPreset`                                                                                                        | `"lg"`        |

#### Returns

[Section titled “Returns”](#returns-10)

`string`

# Listener

```ts
type Listener<K> = (e) => void;
```

Defined in: packages/asset-uploader-expo/src/upload-task.ts:50

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter                                                                     |
| ---------------------------------------------------------------------------------- |
| `K` *extends* keyof [`UploadEvents`](/api/sdk/src/expo/type-aliases/uploadevents/) |

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                 |
| --------- | -------------------------------------------------------------------- |
| `e`       | [`UploadEvents`](/api/sdk/src/expo/type-aliases/uploadevents/)\[`K`] |

## Returns

[Section titled “Returns”](#returns)

`void`

# UploadTask

Defined in: packages/asset-uploader-expo/src/upload-task.ts:52

## Constructors

[Section titled “Constructors”](#constructors)

### Constructor

[Section titled “Constructor”](#constructor)

```ts
new UploadTask(opts): UploadTask;
```

Defined in: packages/asset-uploader-expo/src/upload-task.ts:72

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                     |
| --------- | ------------------------------------------------------------------------ |
| `opts`    | [`UploadTaskOptions`](/api/sdk/src/expo/type-aliases/uploadtaskoptions/) |

#### Returns

[Section titled “Returns”](#returns)

`UploadTask`

## Properties

[Section titled “Properties”](#properties)

### sessionId

[Section titled “sessionId”](#sessionid)

```ts
readonly sessionId: string;
```

Defined in: packages/asset-uploader-expo/src/upload-task.ts:70

Stable id used to correlate native progress events with this instance.

## Methods

[Section titled “Methods”](#methods)

### abort()

[Section titled “abort()”](#abort)

```ts
abort(): void;
```

Defined in: packages/asset-uploader-expo/src/upload-task.ts:129

#### Returns

[Section titled “Returns”](#returns-1)

`void`

***

### on()

[Section titled “on()”](#on)

```ts
on<K>(event, listener): () => void;
```

Defined in: packages/asset-uploader-expo/src/upload-task.ts:85

#### Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter                                                                     |
| ---------------------------------------------------------------------------------- |
| `K` *extends* keyof [`UploadEvents`](/api/sdk/src/expo/type-aliases/uploadevents/) |

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter  | Type                                                                   |
| ---------- | ---------------------------------------------------------------------- |
| `event`    | `K`                                                                    |
| `listener` | [`Listener`](/api/sdk/src/expo/-internal-/type-aliases/listener/)<`K`> |

#### Returns

[Section titled “Returns”](#returns-2)

() => `void`

***

### start()

[Section titled “start()”](#start)

```ts
start(): Promise<{
  assetId?: string;
  deduped: boolean;
}>;
```

Defined in: packages/asset-uploader-expo/src/upload-task.ts:99

#### Returns

[Section titled “Returns”](#returns-3)

`Promise`<{ `assetId?`: `string`; `deduped`: `boolean`; }>

# cancelResumableSession

```ts
function cancelResumableSession(sessionId): Promise<void>;
```

Defined in: packages/asset-uploader-expo/src/index.ts:34

Forcefully cancel a session — drops any in-flight native task and removes its persisted state. Idempotent: safe to call on a sessionId that no longer has any work pending.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter   | Type     |
| ----------- | -------- |
| `sessionId` | `string` |

## Returns

[Section titled “Returns”](#returns)

`Promise`<`void`>

# createExpoUploader

```ts
function createExpoUploader(client, options): UploadTask;
```

Defined in: packages/sdk/src/expo/index.ts:44

Spawn a native-backed `UploadTask` bound to a configured client. Inherits the client’s endpoint / api key / tenant scope; caller only has to supply the file input + any per-upload tuning (partSize, concurrency).

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                     |
| --------- | ------------------------------------------------------------------------ |
| `client`  | [`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/)                 |
| `options` | [`ExpoUploadOptions`](/api/sdk/src/expo/type-aliases/expouploadoptions/) |

## Returns

[Section titled “Returns”](#returns)

[`UploadTask`](/api/sdk/src/expo/classes/uploadtask/)

# listResumableSessions

```ts
function listResumableSessions(): Promise<string[]>;
```

Defined in: packages/asset-uploader-expo/src/index.ts:25

Enumerate session IDs the native layer is currently tracking from a previous app launch. Used by the Resume banner UI on app start.

iOS: pulls from URLSession.background’s persisted task list + the small state file we maintain in NSUserDefaults. Android: pulls from WorkManager via tag scan + EncryptedSharedPrefs.

## Returns

[Section titled “Returns”](#returns)

`Promise`<`string`\[]>

# ExpoUploadOptions

```ts
type ExpoUploadOptions = Omit<UploadTaskOptions, "tenantCode" | "endpoint" | "authToken">;
```

Defined in: packages/sdk/src/expo/index.ts:36

# UploadEvents

```ts
type UploadEvents = {
  done: {
     assetId?: string;
     deduped: boolean;
  };
  error: {
     error: Error;
     recoverable: boolean;
  };
  partCompleted: {
     etag: string;
     partNumber: number;
  };
  progress: {
     bytesUploaded: number;
     ratio: number;
     totalBytes: number;
  };
  ready: {
     assetId?: string;
     deduped: boolean;
     sha256: string;
  };
};
```

Defined in: packages/asset-uploader-expo/src/types.ts:27

## Properties

[Section titled “Properties”](#properties)

### done

[Section titled “done”](#done)

```ts
done: {
  assetId?: string;
  deduped: boolean;
};
```

Defined in: packages/asset-uploader-expo/src/types.ts:32

#### assetId?

[Section titled “assetId?”](#assetid)

```ts
optional assetId?: string;
```

#### deduped

[Section titled “deduped”](#deduped)

```ts
deduped: boolean;
```

***

### error

[Section titled “error”](#error)

```ts
error: {
  error: Error;
  recoverable: boolean;
};
```

Defined in: packages/asset-uploader-expo/src/types.ts:31

#### error

[Section titled “error”](#error-1)

```ts
error: Error;
```

#### recoverable

[Section titled “recoverable”](#recoverable)

```ts
recoverable: boolean;
```

***

### partCompleted

[Section titled “partCompleted”](#partcompleted)

```ts
partCompleted: {
  etag: string;
  partNumber: number;
};
```

Defined in: packages/asset-uploader-expo/src/types.ts:29

#### etag

[Section titled “etag”](#etag)

```ts
etag: string;
```

#### partNumber

[Section titled “partNumber”](#partnumber)

```ts
partNumber: number;
```

***

### progress

[Section titled “progress”](#progress)

```ts
progress: {
  bytesUploaded: number;
  ratio: number;
  totalBytes: number;
};
```

Defined in: packages/asset-uploader-expo/src/types.ts:28

#### bytesUploaded

[Section titled “bytesUploaded”](#bytesuploaded)

```ts
bytesUploaded: number;
```

#### ratio

[Section titled “ratio”](#ratio)

```ts
ratio: number;
```

#### totalBytes

[Section titled “totalBytes”](#totalbytes)

```ts
totalBytes: number;
```

***

### ready

[Section titled “ready”](#ready)

```ts
ready: {
  assetId?: string;
  deduped: boolean;
  sha256: string;
};
```

Defined in: packages/asset-uploader-expo/src/types.ts:30

#### assetId?

[Section titled “assetId?”](#assetid-1)

```ts
optional assetId?: string;
```

#### deduped

[Section titled “deduped”](#deduped-1)

```ts
deduped: boolean;
```

#### sha256

[Section titled “sha256”](#sha256)

```ts
sha256: string;
```

# UploadFileInput

```ts
type UploadFileInput = {
  mime: string;
  name?: string;
  size?: number;
  uri: string;
};
```

Defined in: packages/asset-uploader-expo/src/types.ts:16

Public types for @aquienpz/asset-uploader-expo.

Mirrors @aquienpz/asset-uploader-web/src/upload-task.ts so call sites are identical:

const task = new UploadTask({ uri, mime, tenantCode, endpoint }); task.on(‘progress’, ({ ratio }) => …) await task.start();

The `file: File` of the web API becomes `{ uri, mime, name?, size? }` on mobile because there is no `File` blob — the picker hands us a content:// or file:// URI from expo-image-picker / expo-document-picker.

## Properties

[Section titled “Properties”](#properties)

### mime

[Section titled “mime”](#mime)

```ts
mime: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:20

MIME type. Pickers usually report it; required to drive presets server-side.

***

### name?

[Section titled “name?”](#name)

```ts
optional name?: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:22

Optional friendly name. Defaults to the URI’s basename.

***

### size?

[Section titled “size?”](#size)

```ts
optional size?: number;
```

Defined in: packages/asset-uploader-expo/src/types.ts:24

Optional pre-computed size in bytes. Native side will stat() if omitted.

***

### uri

[Section titled “uri”](#uri)

```ts
uri: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:18

Local URI from a picker (file://, content://, ph://, etc).

# UploadSessionState

```ts
type UploadSessionState = {
  createdAt: number;
  partsCompleted: {
     bytes: number;
     etag: string;
     partNumber: number;
  }[];
  partSize: number;
  sha256: string;
  tenantCode: string;
  totalBytes: number;
  uploadId: string;
  uri: string;
};
```

Defined in: packages/asset-uploader-expo/src/types.ts:77

State persisted across app launches so a kill -9’d upload resumes. Lives natively (NSUserDefaults / Room) and mirrored to JS via events.

## Properties

[Section titled “Properties”](#properties)

### createdAt

[Section titled “createdAt”](#createdat)

```ts
createdAt: number;
```

Defined in: packages/asset-uploader-expo/src/types.ts:85

***

### partsCompleted

[Section titled “partsCompleted”](#partscompleted)

```ts
partsCompleted: {
  bytes: number;
  etag: string;
  partNumber: number;
}[];
```

Defined in: packages/asset-uploader-expo/src/types.ts:84

#### bytes

[Section titled “bytes”](#bytes)

```ts
bytes: number;
```

#### etag

[Section titled “etag”](#etag)

```ts
etag: string;
```

#### partNumber

[Section titled “partNumber”](#partnumber)

```ts
partNumber: number;
```

***

### partSize

[Section titled “partSize”](#partsize)

```ts
partSize: number;
```

Defined in: packages/asset-uploader-expo/src/types.ts:83

***

### sha256

[Section titled “sha256”](#sha256)

```ts
sha256: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:81

***

### tenantCode

[Section titled “tenantCode”](#tenantcode)

```ts
tenantCode: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:79

***

### totalBytes

[Section titled “totalBytes”](#totalbytes)

```ts
totalBytes: number;
```

Defined in: packages/asset-uploader-expo/src/types.ts:82

***

### uploadId

[Section titled “uploadId”](#uploadid)

```ts
uploadId: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:78

***

### uri

[Section titled “uri”](#uri)

```ts
uri: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:80

# UploadTaskOptions

```ts
type UploadTaskOptions = {
  apiHeaders?: Record<string, string>;
  authToken?: string;
  concurrency?: number;
  endpoint: string;
  file: UploadFileInput;
  originalBytes?: number;
  partSize?: number;
  presets?: string[];
  tenantCode: string;
};
```

Defined in: packages/asset-uploader-expo/src/types.ts:35

## Properties

[Section titled “Properties”](#properties)

### apiHeaders?

[Section titled “apiHeaders?”](#apiheaders)

```ts
optional apiHeaders?: Record<string, string>;
```

Defined in: packages/asset-uploader-expo/src/types.ts:49

Extra headers sent ONLY on the asset-manager API calls (`/assets/upload-url`, multipart init/complete, etc.) — never on the direct R2 byte PUT, whose headers come from the presign response. Used by Expo clients to attach the Better Auth session `Cookie` (the documented Expo auth pattern), since the native uploader can’t send cookies automatically.

***

### authToken?

[Section titled “authToken?”](#authtoken)

```ts
optional authToken?: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:41

Optional bearer token (proxy normally injects this on the wire).

***

### concurrency?

[Section titled “concurrency?”](#concurrency)

```ts
optional concurrency?: number;
```

Defined in: packages/asset-uploader-expo/src/types.ts:51

***

### endpoint

[Section titled “endpoint”](#endpoint)

```ts
endpoint: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:39

Asset-manager API base URL. Same field as web.

***

### file

[Section titled “file”](#file)

```ts
file: UploadFileInput;
```

Defined in: packages/asset-uploader-expo/src/types.ts:36

***

### originalBytes?

[Section titled “originalBytes?”](#originalbytes)

```ts
optional originalBytes?: number;
```

Defined in: packages/asset-uploader-expo/src/types.ts:70

Pre-compression byte count from the client. Forwarded to the server so the asset detail UI can show the savings ratio. Set to the size BEFORE any client-side compression. If you didn’t compress (or the compression inflated and you fell back to the original), pass `file.size` here so original == uploaded.

***

### partSize?

[Section titled “partSize?”](#partsize)

```ts
optional partSize?: number;
```

Defined in: packages/asset-uploader-expo/src/types.ts:50

***

### presets?

[Section titled “presets?”](#presets)

```ts
optional presets?: string[];
```

Defined in: packages/asset-uploader-expo/src/types.ts:62

Variant presets to generate server-side — e.g. the image responsive ladder `["thumb","sm","md","lg","xl"]` or video `["poster","video","aiproxy","probe"]`. Forwarded to `/assets/upload-url` and `/assets/multipart/initiate`. Omit to inherit the server default (currently `["original"]` only — meaning responsive/poster variants won’t exist and gallery URLs will 404). The high-level `aq.upload(file, { presets })` sends this; the low-level UploadTask needs it passed explicitly. Kept as `string[]` (server validates names) so newer presets like `probe` don’t need a type bump.

***

### tenantCode

[Section titled “tenantCode”](#tenantcode)

```ts
tenantCode: string;
```

Defined in: packages/asset-uploader-expo/src/types.ts:37

# mimeFromFileName

```ts
function mimeFromFileName(fileName): string | null;
```

Defined in: packages/sdk/src/index.ts:821

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter  | Type                    |
| ---------- | ----------------------- |
| `fileName` | `string` \| `undefined` |

## Returns

[Section titled “Returns”](#returns)

`string` | `null`

# Component

Defined in: node\_modules/@types/react/index.d.ts:909

## Extends

[Section titled “Extends”](#extends)

* [`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/)<`P`, `S`, `SS`>

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Default type |
| -------------- | ------------ |
| `P`            | { }          |
| `S`            | { }          |
| `SS`           | `any`        |

## Constructors

[Section titled “Constructors”](#constructors)

### Constructor

[Section titled “Constructor”](#constructor)

```ts
new Component<P, S, SS>(props): Component<P, S, SS>;
```

Defined in: node\_modules/@types/react/index.d.ts:958

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type |
| --------- | ---- |
| `props`   | `P`  |

#### Returns

[Section titled “Returns”](#returns)

`Component`<`P`, `S`, `SS`>

#### Inherited from

[Section titled “Inherited from”](#inherited-from)

```ts
ComponentLifecycle<P, S, SS>.constructor
```

### Constructor

[Section titled “Constructor”](#constructor-1)

```ts
new Component<P, S, SS>(props, context): Component<P, S, SS>;
```

Defined in: node\_modules/@types/react/index.d.ts:966

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter | Type  | Description                                                                                                    |
| --------- | ----- | -------------------------------------------------------------------------------------------------------------- |
| `props`   | `P`   | -                                                                                                              |
| `context` | `any` | value of the parent [Context](https://react.dev/reference/react/Component#context) specified in `contextType`. |

#### Returns

[Section titled “Returns”](#returns-1)

`Component`<`P`, `S`, `SS`>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-1)

```ts
ComponentLifecycle<P, S, SS>.constructor
```

## Properties

[Section titled “Properties”](#properties)

### context

[Section titled “context”](#context)

```ts
context: unknown;
```

Defined in: node\_modules/@types/react/index.d.ts:955

If using React Context, re-declare this in your class to be the `React.ContextType` of your `static contextType`. Should be used with type annotation or static contextType.

#### Example

[Section titled “Example”](#example)

```ts
static contextType = MyContext
// For TS pre-3.7:
context!: React.ContextType<typeof MyContext>
// For TS 3.7 and above:
declare context: React.ContextType<typeof MyContext>
```

#### See

[Section titled “See”](#see)

[React Docs](https://react.dev/reference/react/Component#context)

***

### props

[Section titled “props”](#props)

```ts
readonly props: Readonly<P>;
```

Defined in: node\_modules/@types/react/index.d.ts:979

***

### state

[Section titled “state”](#state)

```ts
state: Readonly<S>;
```

Defined in: node\_modules/@types/react/index.d.ts:980

***

### contextType?

[Section titled “contextType?”](#contexttype)

```ts
static optional contextType?: Context<any>;
```

Defined in: node\_modules/@types/react/index.d.ts:931

If set, `this.context` will be set at runtime to the current value of the given Context.

#### Example

[Section titled “Example”](#example-1)

```ts
type MyContext = number
const Ctx = React.createContext<MyContext>(0)


class Foo extends React.Component {
  static contextType = Ctx
  context!: React.ContextType<typeof Ctx>
  render () {
    return <>My context's value: {this.context}</>;
  }
}
```

#### See

[Section titled “See”](#see-1)

<https://react.dev/reference/react/Component#static-contexttype>

***

### ~~propTypes?~~

[Section titled “propTypes?”](#proptypes)

```ts
static optional propTypes?: any;
```

Defined in: node\_modules/@types/react/index.d.ts:937

Ignored by React.

Deprecated

Only kept in types for backwards compatibility. Will be removed in a future major release.

## Methods

[Section titled “Methods”](#methods)

### componentDidCatch()?

[Section titled “componentDidCatch()?”](#componentdidcatch)

```ts
optional componentDidCatch(error, errorInfo): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1219

Catches exceptions generated in descendant components. Unhandled exceptions will cause the entire component tree to unmount.

#### Parameters

[Section titled “Parameters”](#parameters-2)

| Parameter   | Type                                                               |
| ----------- | ------------------------------------------------------------------ |
| `error`     | `Error`                                                            |
| `errorInfo` | [`ErrorInfo`](/api/sdk/src/react/-internal-/interfaces/errorinfo/) |

#### Returns

[Section titled “Returns”](#returns-2)

`void`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-2)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`componentDidCatch`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentdidcatch)

***

### componentDidMount()?

[Section titled “componentDidMount()?”](#componentdidmount)

```ts
optional componentDidMount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1198

Called immediately after a component is mounted. Setting state here will trigger re-rendering.

#### Returns

[Section titled “Returns”](#returns-3)

`void`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-3)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`componentDidMount`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentdidmount)

***

### componentDidUpdate()?

[Section titled “componentDidUpdate()?”](#componentdidupdate)

```ts
optional componentDidUpdate(
   prevProps,
   prevState,
   snapshot?): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1261

Called immediately after updating occurs. Not called for the initial render.

The snapshot is only present if [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) is present and returns non-null.

#### Parameters

[Section titled “Parameters”](#parameters-3)

| Parameter   | Type                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| `prevProps` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `prevState` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `snapshot?` | `SS`                                                                    |

#### Returns

[Section titled “Returns”](#returns-4)

`void`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-4)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`componentDidUpdate`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentdidupdate)

***

### ~~componentWillMount()?~~

[Section titled “componentWillMount()?”](#componentwillmount)

```ts
optional componentWillMount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1277

Called immediately before mounting occurs, and before [Component.render](/api/sdk/src/react/-internal-/classes/component/#render). Avoid introducing any side-effects or subscriptions in this method.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use [componentDidMount](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentdidmount) or the constructor instead; will stop working in React 17

#### Returns

[Section titled “Returns”](#returns-5)

`void`

#### See

[Section titled “See”](#see-2)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-5)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`componentWillMount`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentwillmount)

***

### ~~componentWillReceiveProps()?~~

[Section titled “componentWillReceiveProps()?”](#componentwillreceiveprops)

```ts
optional componentWillReceiveProps(nextProps, nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1308

Called when the component may be receiving new props. React may call this even if props have not changed, so be sure to compare new and existing props if you only want to handle changes.

Calling [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) generally does not trigger this method.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead; will stop working in React 17

#### Parameters

[Section titled “Parameters”](#parameters-4)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-6)

`void`

#### See

[Section titled “See”](#see-3)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-6)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`componentWillReceiveProps`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentwillreceiveprops)

***

### componentWillUnmount()?

[Section titled “componentWillUnmount()?”](#componentwillunmount)

```ts
optional componentWillUnmount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1214

Called immediately before a component is destroyed. Perform any necessary cleanup in this method, such as cancelled network requests, or cleaning up any DOM elements created in `componentDidMount`.

#### Returns

[Section titled “Returns”](#returns-7)

`void`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-7)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`componentWillUnmount`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentwillunmount)

***

### ~~componentWillUpdate()?~~

[Section titled “componentWillUpdate()?”](#componentwillupdate)

```ts
optional componentWillUpdate(
   nextProps,
   nextState,
   nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1340

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) here.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use getSnapshotBeforeUpdate instead; will stop working in React 17

#### Parameters

[Section titled “Parameters”](#parameters-5)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextState`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-8)

`void`

#### See

[Section titled “See”](#see-4)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-8)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`componentWillUpdate`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentwillupdate)

***

### forceUpdate()

[Section titled “forceUpdate()”](#forceupdate)

```ts
forceUpdate(callback?): void;
```

Defined in: node\_modules/@types/react/index.d.ts:976

#### Parameters

[Section titled “Parameters”](#parameters-6)

| Parameter   | Type         |
| ----------- | ------------ |
| `callback?` | () => `void` |

#### Returns

[Section titled “Returns”](#returns-9)

`void`

***

### getSnapshotBeforeUpdate()?

[Section titled “getSnapshotBeforeUpdate()?”](#getsnapshotbeforeupdate)

```ts
optional getSnapshotBeforeUpdate(prevProps, prevState): SS | null;
```

Defined in: node\_modules/@types/react/index.d.ts:1255

Runs before React applies the result of [render](/api/sdk/src/react/-internal-/classes/component/#render) to the document, and returns an object to be given to [componentDidUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#componentdidupdate). Useful for saving things such as scroll position before [render](/api/sdk/src/react/-internal-/classes/component/#render) causes changes to it.

Note: the presence of this method prevents any of the deprecated lifecycle events from running.

#### Parameters

[Section titled “Parameters”](#parameters-7)

| Parameter   | Type                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| `prevProps` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `prevState` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |

#### Returns

[Section titled “Returns”](#returns-10)

`SS` | `null`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-9)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`getSnapshotBeforeUpdate`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#getsnapshotbeforeupdate)

***

### render()

[Section titled “render()”](#render)

```ts
render(): ReactNode;
```

Defined in: node\_modules/@types/react/index.d.ts:977

#### Returns

[Section titled “Returns”](#returns-11)

[`ReactNode`](/api/sdk/src/react/-internal-/type-aliases/reactnode/)

***

### setState()

[Section titled “setState()”](#setstate)

```ts
setState<K>(state, callback?): void;
```

Defined in: node\_modules/@types/react/index.d.ts:971

#### Type Parameters

[Section titled “Type Parameters”](#type-parameters-1)

| Type Parameter                                 |
| ---------------------------------------------- |
| `K` *extends* `string` \| `number` \| `symbol` |

#### Parameters

[Section titled “Parameters”](#parameters-8)

| Parameter   | Type                                                                                                                                                                                                             |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`     | \| `S` \| ((`prevState`, `props`) => \| `S` \| [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<`S`, `K`> \| `null`) \| [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<`S`, `K`> \| `null` |
| `callback?` | () => `void`                                                                                                                                                                                                     |

#### Returns

[Section titled “Returns”](#returns-12)

`void`

***

### shouldComponentUpdate()?

[Section titled “shouldComponentUpdate()?”](#shouldcomponentupdate)

```ts
optional shouldComponentUpdate(
   nextProps,
   nextState,
   nextContext): boolean;
```

Defined in: node\_modules/@types/react/index.d.ts:1209

Called to determine whether the change in props and state should trigger a re-render.

`Component` always returns true. `PureComponent` implements a shallow comparison on props and state and returns true if any props or states have changed.

If false is returned, [Component.render](/api/sdk/src/react/-internal-/classes/component/#render), `componentWillUpdate` and `componentDidUpdate` will not be called.

#### Parameters

[Section titled “Parameters”](#parameters-9)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextState`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-13)

`boolean`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-10)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`shouldComponentUpdate`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#shouldcomponentupdate)

***

### ~~UNSAFE\_componentWillMount()?~~

[Section titled “UNSAFE\_componentWillMount()?”](#unsafe_componentwillmount)

```ts
optional UNSAFE_componentWillMount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1292

Called immediately before mounting occurs, and before [Component.render](/api/sdk/src/react/-internal-/classes/component/#render). Avoid introducing any side-effects or subscriptions in this method.

This method will not stop working in React 17.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use [componentDidMount](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentdidmount) or the constructor instead

#### Returns

[Section titled “Returns”](#returns-14)

`void`

#### See

[Section titled “See”](#see-5)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-11)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`UNSAFE_componentWillMount`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#unsafe_componentwillmount)

***

### ~~UNSAFE\_componentWillReceiveProps()?~~

[Section titled “UNSAFE\_componentWillReceiveProps()?”](#unsafe_componentwillreceiveprops)

```ts
optional UNSAFE_componentWillReceiveProps(nextProps, nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1326

Called when the component may be receiving new props. React may call this even if props have not changed, so be sure to compare new and existing props if you only want to handle changes.

Calling [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) generally does not trigger this method.

This method will not stop working in React 17.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead

#### Parameters

[Section titled “Parameters”](#parameters-10)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-15)

`void`

#### See

[Section titled “See”](#see-6)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-12)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`UNSAFE_componentWillReceiveProps`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#unsafe_componentwillreceiveprops)

***

### ~~UNSAFE\_componentWillUpdate()?~~

[Section titled “UNSAFE\_componentWillUpdate()?”](#unsafe_componentwillupdate)

```ts
optional UNSAFE_componentWillUpdate(
   nextProps,
   nextState,
   nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1356

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) here.

This method will not stop working in React 17.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use getSnapshotBeforeUpdate instead

#### Parameters

[Section titled “Parameters”](#parameters-11)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextState`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-16)

`void`

#### See

[Section titled “See”](#see-7)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-13)

[`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/).[`UNSAFE_componentWillUpdate`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#unsafe_componentwillupdate)

# ComponentLifecycle

Defined in: node\_modules/@types/react/index.d.ts:1194

## Extends

[Section titled “Extends”](#extends)

* [`NewLifecycle`](/api/sdk/src/react/-internal-/interfaces/newlifecycle/)<`P`, `S`, `SS`>.[`DeprecatedLifecycle`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/)<`P`, `S`>

## Extended by

[Section titled “Extended by”](#extended-by)

* [`Component`](/api/sdk/src/react/-internal-/classes/component/)

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Default type |
| -------------- | ------------ |
| `P`            | -            |
| `S`            | -            |
| `SS`           | `any`        |

## Methods

[Section titled “Methods”](#methods)

### componentDidCatch()?

[Section titled “componentDidCatch()?”](#componentdidcatch)

```ts
optional componentDidCatch(error, errorInfo): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1219

Catches exceptions generated in descendant components. Unhandled exceptions will cause the entire component tree to unmount.

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter   | Type                                                               |
| ----------- | ------------------------------------------------------------------ |
| `error`     | `Error`                                                            |
| `errorInfo` | [`ErrorInfo`](/api/sdk/src/react/-internal-/interfaces/errorinfo/) |

#### Returns

[Section titled “Returns”](#returns)

`void`

***

### componentDidMount()?

[Section titled “componentDidMount()?”](#componentdidmount)

```ts
optional componentDidMount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1198

Called immediately after a component is mounted. Setting state here will trigger re-rendering.

#### Returns

[Section titled “Returns”](#returns-1)

`void`

***

### componentDidUpdate()?

[Section titled “componentDidUpdate()?”](#componentdidupdate)

```ts
optional componentDidUpdate(
   prevProps,
   prevState,
   snapshot?): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1261

Called immediately after updating occurs. Not called for the initial render.

The snapshot is only present if [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) is present and returns non-null.

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter   | Type                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| `prevProps` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `prevState` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `snapshot?` | `SS`                                                                    |

#### Returns

[Section titled “Returns”](#returns-2)

`void`

#### Inherited from

[Section titled “Inherited from”](#inherited-from)

[`NewLifecycle`](/api/sdk/src/react/-internal-/interfaces/newlifecycle/).[`componentDidUpdate`](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#componentdidupdate)

***

### ~~componentWillMount()?~~

[Section titled “componentWillMount()?”](#componentwillmount)

```ts
optional componentWillMount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1277

Called immediately before mounting occurs, and before [Component.render](/api/sdk/src/react/-internal-/classes/component/#render). Avoid introducing any side-effects or subscriptions in this method.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use [componentDidMount](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentdidmount) or the constructor instead; will stop working in React 17

#### Returns

[Section titled “Returns”](#returns-3)

`void`

#### See

[Section titled “See”](#see)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-1)

[`DeprecatedLifecycle`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/).[`componentWillMount`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/#componentwillmount)

***

### ~~componentWillReceiveProps()?~~

[Section titled “componentWillReceiveProps()?”](#componentwillreceiveprops)

```ts
optional componentWillReceiveProps(nextProps, nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1308

Called when the component may be receiving new props. React may call this even if props have not changed, so be sure to compare new and existing props if you only want to handle changes.

Calling [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) generally does not trigger this method.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead; will stop working in React 17

#### Parameters

[Section titled “Parameters”](#parameters-2)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-4)

`void`

#### See

[Section titled “See”](#see-1)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-2)

[`DeprecatedLifecycle`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/).[`componentWillReceiveProps`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/#componentwillreceiveprops)

***

### componentWillUnmount()?

[Section titled “componentWillUnmount()?”](#componentwillunmount)

```ts
optional componentWillUnmount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1214

Called immediately before a component is destroyed. Perform any necessary cleanup in this method, such as cancelled network requests, or cleaning up any DOM elements created in `componentDidMount`.

#### Returns

[Section titled “Returns”](#returns-5)

`void`

***

### ~~componentWillUpdate()?~~

[Section titled “componentWillUpdate()?”](#componentwillupdate)

```ts
optional componentWillUpdate(
   nextProps,
   nextState,
   nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1340

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) here.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use getSnapshotBeforeUpdate instead; will stop working in React 17

#### Parameters

[Section titled “Parameters”](#parameters-3)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextState`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-6)

`void`

#### See

[Section titled “See”](#see-2)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-3)

[`DeprecatedLifecycle`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/).[`componentWillUpdate`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/#componentwillupdate)

***

### getSnapshotBeforeUpdate()?

[Section titled “getSnapshotBeforeUpdate()?”](#getsnapshotbeforeupdate)

```ts
optional getSnapshotBeforeUpdate(prevProps, prevState): SS | null;
```

Defined in: node\_modules/@types/react/index.d.ts:1255

Runs before React applies the result of [render](/api/sdk/src/react/-internal-/classes/component/#render) to the document, and returns an object to be given to [componentDidUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#componentdidupdate). Useful for saving things such as scroll position before [render](/api/sdk/src/react/-internal-/classes/component/#render) causes changes to it.

Note: the presence of this method prevents any of the deprecated lifecycle events from running.

#### Parameters

[Section titled “Parameters”](#parameters-4)

| Parameter   | Type                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| `prevProps` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `prevState` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |

#### Returns

[Section titled “Returns”](#returns-7)

`SS` | `null`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-4)

[`NewLifecycle`](/api/sdk/src/react/-internal-/interfaces/newlifecycle/).[`getSnapshotBeforeUpdate`](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate)

***

### shouldComponentUpdate()?

[Section titled “shouldComponentUpdate()?”](#shouldcomponentupdate)

```ts
optional shouldComponentUpdate(
   nextProps,
   nextState,
   nextContext): boolean;
```

Defined in: node\_modules/@types/react/index.d.ts:1209

Called to determine whether the change in props and state should trigger a re-render.

`Component` always returns true. `PureComponent` implements a shallow comparison on props and state and returns true if any props or states have changed.

If false is returned, [Component.render](/api/sdk/src/react/-internal-/classes/component/#render), `componentWillUpdate` and `componentDidUpdate` will not be called.

#### Parameters

[Section titled “Parameters”](#parameters-5)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextState`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-8)

`boolean`

***

### ~~UNSAFE\_componentWillMount()?~~

[Section titled “UNSAFE\_componentWillMount()?”](#unsafe_componentwillmount)

```ts
optional UNSAFE_componentWillMount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1292

Called immediately before mounting occurs, and before [Component.render](/api/sdk/src/react/-internal-/classes/component/#render). Avoid introducing any side-effects or subscriptions in this method.

This method will not stop working in React 17.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use [componentDidMount](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentdidmount) or the constructor instead

#### Returns

[Section titled “Returns”](#returns-9)

`void`

#### See

[Section titled “See”](#see-3)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-5)

[`DeprecatedLifecycle`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/).[`UNSAFE_componentWillMount`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/#unsafe_componentwillmount)

***

### ~~UNSAFE\_componentWillReceiveProps()?~~

[Section titled “UNSAFE\_componentWillReceiveProps()?”](#unsafe_componentwillreceiveprops)

```ts
optional UNSAFE_componentWillReceiveProps(nextProps, nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1326

Called when the component may be receiving new props. React may call this even if props have not changed, so be sure to compare new and existing props if you only want to handle changes.

Calling [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) generally does not trigger this method.

This method will not stop working in React 17.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead

#### Parameters

[Section titled “Parameters”](#parameters-6)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-10)

`void`

#### See

[Section titled “See”](#see-4)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-6)

[`DeprecatedLifecycle`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/).[`UNSAFE_componentWillReceiveProps`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/#unsafe_componentwillreceiveprops)

***

### ~~UNSAFE\_componentWillUpdate()?~~

[Section titled “UNSAFE\_componentWillUpdate()?”](#unsafe_componentwillupdate)

```ts
optional UNSAFE_componentWillUpdate(
   nextProps,
   nextState,
   nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1356

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) here.

This method will not stop working in React 17.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use getSnapshotBeforeUpdate instead

#### Parameters

[Section titled “Parameters”](#parameters-7)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextState`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-11)

`void`

#### See

[Section titled “See”](#see-5)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

#### Inherited from

[Section titled “Inherited from”](#inherited-from-7)

[`DeprecatedLifecycle`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/).[`UNSAFE_componentWillUpdate`](/api/sdk/src/react/-internal-/interfaces/deprecatedlifecycle/#unsafe_componentwillupdate)

# ConsumerProps

Defined in: node\_modules/@types/react/index.d.ts:554

Describes the props accepted by a Context [Consumer](/api/sdk/src/react/-internal-/type-aliases/consumer/).

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Description                                 |
| -------------- | ------------------------------------------- |
| `T`            | The type of the value the context provides. |

## Properties

[Section titled “Properties”](#properties)

### children

[Section titled “children”](#children)

```ts
children: (value) => ReactNode;
```

Defined in: node\_modules/@types/react/index.d.ts:555

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type |
| --------- | ---- |
| `value`   | `T`  |

#### Returns

[Section titled “Returns”](#returns)

[`ReactNode`](/api/sdk/src/react/-internal-/type-aliases/reactnode/)

# Context

Defined in: node\_modules/@types/react/index.d.ts:678

Context lets components pass information deep down without explicitly passing props.

Created from createContext

## See

[Section titled “See”](#see)

* [React Docs](https://react.dev/learn/passing-data-deeply-with-context)
* [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/context/)

## Example

[Section titled “Example”](#example)

```tsx
import { createContext } from 'react';


const ThemeContext = createContext('light');
```

## Extends

[Section titled “Extends”](#extends)

* [`Provider`](/api/sdk/src/react/-internal-/type-aliases/provider/)<`T`>

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `T`            |

```ts
Context(props): ReactNode;
```

Defined in: node\_modules/@types/react/index.d.ts:678

Context lets components pass information deep down without explicitly passing props.

Created from createContext

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                       |
| --------- | -------------------------------------------------------------------------- |
| `props`   | [`ProviderProps`](/api/sdk/src/react/-internal-/interfaces/providerprops/) |

## Returns

[Section titled “Returns”](#returns)

[`ReactNode`](/api/sdk/src/react/-internal-/type-aliases/reactnode/)

## See

[Section titled “See”](#see-1)

* [React Docs](https://react.dev/learn/passing-data-deeply-with-context)
* [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/context/)

## Example

[Section titled “Example”](#example-1)

```tsx
import { createContext } from 'react';


const ThemeContext = createContext('light');
```

## Properties

[Section titled “Properties”](#properties)

### $$typeof

[Section titled “$$typeof”](#typeof)

```ts
readonly $$typeof: symbol;
```

Defined in: node\_modules/@types/react/index.d.ts:572

#### Inherited from

[Section titled “Inherited from”](#inherited-from)

[`ProviderExoticComponent`](/api/sdk/src/react/-internal-/interfaces/providerexoticcomponent/).[`$$typeof`](/api/sdk/src/react/-internal-/interfaces/providerexoticcomponent/#typeof)

***

### Consumer

[Section titled “Consumer”](#consumer)

```ts
Consumer: Consumer<T>;
```

Defined in: node\_modules/@types/react/index.d.ts:680

***

### displayName?

[Section titled “displayName?”](#displayname)

```ts
optional displayName?: string;
```

Defined in: node\_modules/@types/react/index.d.ts:688

Used in debugging messages. You might want to set it explicitly if you want to display a different name for debugging purposes.

#### See

[Section titled “See”](#see-2)

[Legacy React Docs](https://legacy.reactjs.org/docs/react-component.html#displayname)

***

### Provider

[Section titled “Provider”](#provider)

```ts
Provider: Provider<T>;
```

Defined in: node\_modules/@types/react/index.d.ts:679

# DeprecatedLifecycle

Defined in: node\_modules/@types/react/index.d.ts:1264

## Extended by

[Section titled “Extended by”](#extended-by)

* [`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/)

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `P`            |
| `S`            |

## Methods

[Section titled “Methods”](#methods)

### ~~componentWillMount()?~~

[Section titled “componentWillMount()?”](#componentwillmount)

```ts
optional componentWillMount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1277

Called immediately before mounting occurs, and before [Component.render](/api/sdk/src/react/-internal-/classes/component/#render). Avoid introducing any side-effects or subscriptions in this method.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use [componentDidMount](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentdidmount) or the constructor instead; will stop working in React 17

#### Returns

[Section titled “Returns”](#returns)

`void`

#### See

[Section titled “See”](#see)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

***

### ~~componentWillReceiveProps()?~~

[Section titled “componentWillReceiveProps()?”](#componentwillreceiveprops)

```ts
optional componentWillReceiveProps(nextProps, nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1308

Called when the component may be receiving new props. React may call this even if props have not changed, so be sure to compare new and existing props if you only want to handle changes.

Calling [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) generally does not trigger this method.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead; will stop working in React 17

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-1)

`void`

#### See

[Section titled “See”](#see-1)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

***

### ~~componentWillUpdate()?~~

[Section titled “componentWillUpdate()?”](#componentwillupdate)

```ts
optional componentWillUpdate(
   nextProps,
   nextState,
   nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1340

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) here.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use getSnapshotBeforeUpdate instead; will stop working in React 17

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextState`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-2)

`void`

#### See

[Section titled “See”](#see-2)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

***

### ~~UNSAFE\_componentWillMount()?~~

[Section titled “UNSAFE\_componentWillMount()?”](#unsafe_componentwillmount)

```ts
optional UNSAFE_componentWillMount(): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1292

Called immediately before mounting occurs, and before [Component.render](/api/sdk/src/react/-internal-/classes/component/#render). Avoid introducing any side-effects or subscriptions in this method.

This method will not stop working in React 17.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use [componentDidMount](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/#componentdidmount) or the constructor instead

#### Returns

[Section titled “Returns”](#returns-3)

`void`

#### See

[Section titled “See”](#see-3)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

***

### ~~UNSAFE\_componentWillReceiveProps()?~~

[Section titled “UNSAFE\_componentWillReceiveProps()?”](#unsafe_componentwillreceiveprops)

```ts
optional UNSAFE_componentWillReceiveProps(nextProps, nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1326

Called when the component may be receiving new props. React may call this even if props have not changed, so be sure to compare new and existing props if you only want to handle changes.

Calling [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) generally does not trigger this method.

This method will not stop working in React 17.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead

#### Parameters

[Section titled “Parameters”](#parameters-2)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-4)

`void`

#### See

[Section titled “See”](#see-4)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

***

### ~~UNSAFE\_componentWillUpdate()?~~

[Section titled “UNSAFE\_componentWillUpdate()?”](#unsafe_componentwillupdate)

```ts
optional UNSAFE_componentWillUpdate(
   nextProps,
   nextState,
   nextContext): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1356

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/sdk/src/react/-internal-/classes/component/#setstate) here.

This method will not stop working in React 17.

Note: the presence of [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents this from being invoked.

Deprecated

16.3, use getSnapshotBeforeUpdate instead

#### Parameters

[Section titled “Parameters”](#parameters-3)

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `nextProps`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `nextState`   | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `nextContext` | `any`                                                                   |

#### Returns

[Section titled “Returns”](#returns-5)

`void`

#### See

[Section titled “See”](#see-5)

* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update>
* <https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path>

# DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_REACT_NODES

Defined in: node\_modules/@types/react/index.d.ts:404

Different release channels declare additional types of ReactNode this particular release channel accepts. App or library types should never augment this interface.

# ErrorInfo

Defined in: node\_modules/@types/react/index.d.ts:4125

## Properties

[Section titled “Properties”](#properties)

### componentStack?

[Section titled “componentStack?”](#componentstack)

```ts
optional componentStack?: string | null;
```

Defined in: node\_modules/@types/react/index.d.ts:4129

Captures which component contained the exception, and its ancestors.

# ExoticComponent

Defined in: node\_modules/@types/react/index.d.ts:570

An object masquerading as a component. These are created by functions like forwardRef, memo, and createContext.

In order to make TypeScript work, we pretend that they are normal components.

But they are, in fact, not callable - instead, they are objects which are treated specially by the renderer.

## Extended by

[Section titled “Extended by”](#extended-by)

* [`ProviderExoticComponent`](/api/sdk/src/react/-internal-/interfaces/providerexoticcomponent/)

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Default type | Description                      |
| -------------- | ------------ | -------------------------------- |
| `P`            | { }          | The props the component accepts. |

```ts
ExoticComponent(props): ReactNode;
```

Defined in: node\_modules/@types/react/index.d.ts:571

An object masquerading as a component. These are created by functions like forwardRef, memo, and createContext.

In order to make TypeScript work, we pretend that they are normal components.

But they are, in fact, not callable - instead, they are objects which are treated specially by the renderer.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type |
| --------- | ---- |
| `props`   | `P`  |

## Returns

[Section titled “Returns”](#returns)

[`ReactNode`](/api/sdk/src/react/-internal-/type-aliases/reactnode/)

## Properties

[Section titled “Properties”](#properties)

### $$typeof

[Section titled “$$typeof”](#typeof)

```ts
readonly $$typeof: symbol;
```

Defined in: node\_modules/@types/react/index.d.ts:572

# Iterable

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:46

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Default type |
| -------------- | ------------ |
| `T`            | -            |
| `TReturn`      | `any`        |
| `TNext`        | `any`        |

## Methods

[Section titled “Methods”](#methods)

### \[iterator]\()

[Section titled “\[iterator\]()”](#iterator)

```ts
iterator: Iterator<T, TReturn, TNext>;
```

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:47

#### Returns

[Section titled “Returns”](#returns)

[`Iterator`](/api/sdk/src/react/-internal-/interfaces/iterator/)<`T`, `TReturn`, `TNext`>

# Iterator

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:39

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Default type |
| -------------- | ------------ |
| `T`            | -            |
| `TReturn`      | `any`        |
| `TNext`        | `any`        |

## Methods

[Section titled “Methods”](#methods)

### next()

[Section titled “next()”](#next)

```ts
next(...__namedParameters): IteratorResult<T, TReturn>;
```

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:41

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter            | Type              |
| -------------------- | ----------------- |
| …`__namedParameters` | \[] \| \[`TNext`] |

#### Returns

[Section titled “Returns”](#returns)

[`IteratorResult`](/api/sdk/src/react/-internal-/type-aliases/iteratorresult/)<`T`, `TReturn`>

***

### return()?

[Section titled “return()?”](#return)

```ts
optional return(value?): IteratorResult<T, TReturn>;
```

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:42

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter | Type      |
| --------- | --------- |
| `value?`  | `TReturn` |

#### Returns

[Section titled “Returns”](#returns-1)

[`IteratorResult`](/api/sdk/src/react/-internal-/type-aliases/iteratorresult/)<`T`, `TReturn`>

***

### throw()?

[Section titled “throw()?”](#throw)

```ts
optional throw(e?): IteratorResult<T, TReturn>;
```

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:43

#### Parameters

[Section titled “Parameters”](#parameters-2)

| Parameter | Type  |
| --------- | ----- |
| `e?`      | `any` |

#### Returns

[Section titled “Returns”](#returns-2)

[`IteratorResult`](/api/sdk/src/react/-internal-/type-aliases/iteratorresult/)<`T`, `TReturn`>

# IteratorReturnResult

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:32

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `TReturn`      |

## Properties

[Section titled “Properties”](#properties)

### done

[Section titled “done”](#done)

```ts
done: true;
```

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:33

***

### value

[Section titled “value”](#value)

```ts
value: TReturn;
```

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:34

# IteratorYieldResult

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:27

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `TYield`       |

## Properties

[Section titled “Properties”](#properties)

### done?

[Section titled “done?”](#done)

```ts
optional done?: false;
```

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:28

***

### value

[Section titled “value”](#value)

```ts
value: TYield;
```

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:29

# NewLifecycle

Defined in: node\_modules/@types/react/index.d.ts:1246

## Extended by

[Section titled “Extended by”](#extended-by)

* [`ComponentLifecycle`](/api/sdk/src/react/-internal-/interfaces/componentlifecycle/)

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `P`            |
| `S`            |
| `SS`           |

## Methods

[Section titled “Methods”](#methods)

### componentDidUpdate()?

[Section titled “componentDidUpdate()?”](#componentdidupdate)

```ts
optional componentDidUpdate(
   prevProps,
   prevState,
   snapshot?): void;
```

Defined in: node\_modules/@types/react/index.d.ts:1261

Called immediately after updating occurs. Not called for the initial render.

The snapshot is only present if [getSnapshotBeforeUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#getsnapshotbeforeupdate) is present and returns non-null.

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter   | Type                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| `prevProps` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `prevState` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |
| `snapshot?` | `SS`                                                                    |

#### Returns

[Section titled “Returns”](#returns)

`void`

***

### getSnapshotBeforeUpdate()?

[Section titled “getSnapshotBeforeUpdate()?”](#getsnapshotbeforeupdate)

```ts
optional getSnapshotBeforeUpdate(prevProps, prevState): SS | null;
```

Defined in: node\_modules/@types/react/index.d.ts:1255

Runs before React applies the result of [render](/api/sdk/src/react/-internal-/classes/component/#render) to the document, and returns an object to be given to [componentDidUpdate](/api/sdk/src/react/-internal-/interfaces/newlifecycle/#componentdidupdate). Useful for saving things such as scroll position before [render](/api/sdk/src/react/-internal-/classes/component/#render) causes changes to it.

Note: the presence of this method prevents any of the deprecated lifecycle events from running.

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter   | Type                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| `prevProps` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`P`> |
| `prevState` | [`Readonly`](/api/sdk/src/react/-internal-/type-aliases/readonly/)<`S`> |

#### Returns

[Section titled “Returns”](#returns-1)

`SS` | `null`

# ProviderExoticComponent

Defined in: node\_modules/@types/react/index.d.ts:596

An [ExoticComponent](/api/sdk/src/react/-internal-/interfaces/exoticcomponent/) with a `propTypes` property applied to it.

## Extends

[Section titled “Extends”](#extends)

* [`ExoticComponent`](/api/sdk/src/react/-internal-/interfaces/exoticcomponent/)<`P`>

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Description                      |
| -------------- | -------------------------------- |
| `P`            | The props the component accepts. |

```ts
ProviderExoticComponent(props): ReactNode;
```

Defined in: node\_modules/@types/react/index.d.ts:596

An [ExoticComponent](/api/sdk/src/react/-internal-/interfaces/exoticcomponent/) with a `propTypes` property applied to it.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type |
| --------- | ---- |
| `props`   | `P`  |

## Returns

[Section titled “Returns”](#returns)

[`ReactNode`](/api/sdk/src/react/-internal-/type-aliases/reactnode/)

## Properties

[Section titled “Properties”](#properties)

### $$typeof

[Section titled “$$typeof”](#typeof)

```ts
readonly $$typeof: symbol;
```

Defined in: node\_modules/@types/react/index.d.ts:572

#### Inherited from

[Section titled “Inherited from”](#inherited-from)

[`ExoticComponent`](/api/sdk/src/react/-internal-/interfaces/exoticcomponent/).[`$$typeof`](/api/sdk/src/react/-internal-/interfaces/exoticcomponent/#typeof)

# ProviderProps

Defined in: node\_modules/@types/react/index.d.ts:544

Describes the props accepted by a Context [Provider](/api/sdk/src/react/-internal-/type-aliases/provider/).

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Description                                 |
| -------------- | ------------------------------------------- |
| `T`            | The type of the value the context provides. |

## Properties

[Section titled “Properties”](#properties)

### children?

[Section titled “children?”](#children)

```ts
optional children?: ReactNode;
```

Defined in: node\_modules/@types/react/index.d.ts:546

***

### value

[Section titled “value”](#value)

```ts
value: T;
```

Defined in: node\_modules/@types/react/index.d.ts:545

# ReactElement

Defined in: node\_modules/@types/react/index.d.ts:325

Represents a JSX element.

Where [ReactNode](/api/sdk/src/react/-internal-/type-aliases/reactnode/) represents everything that can be rendered, `ReactElement` only represents JSX.

## Example

[Section titled “Example”](#example)

```tsx
const element: ReactElement = <div />;
```

## Extended by

[Section titled “Extended by”](#extended-by)

* [`ReactPortal`](/api/sdk/src/react/-internal-/interfaces/reactportal/)

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter                                                                                                                   | Default type                                                                                                       | Description                      |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| `P`                                                                                                                              | `unknown`                                                                                                          | The type of the props object     |
| `T` *extends* \| `string` \| [`JSXElementConstructor`](/api/sdk/src/react/-internal-/type-aliases/jsxelementconstructor/)<`any`> | \| `string` \| [`JSXElementConstructor`](/api/sdk/src/react/-internal-/type-aliases/jsxelementconstructor/)<`any`> | The type of the component or tag |

## Properties

[Section titled “Properties”](#properties)

### key

[Section titled “key”](#key)

```ts
key: string | null;
```

Defined in: node\_modules/@types/react/index.d.ts:331

***

### props

[Section titled “props”](#props)

```ts
props: P;
```

Defined in: node\_modules/@types/react/index.d.ts:330

***

### type

[Section titled “type”](#type)

```ts
type: T;
```

Defined in: node\_modules/@types/react/index.d.ts:329

# ReactPortal

Defined in: node\_modules/@types/react/index.d.ts:396

Represents a JSX element.

Where [ReactNode](/api/sdk/src/react/-internal-/type-aliases/reactnode/) represents everything that can be rendered, `ReactElement` only represents JSX.

## Example

[Section titled “Example”](#example)

```tsx
const element: ReactElement = <div />;
```

## Extends

[Section titled “Extends”](#extends)

* [`ReactElement`](/api/sdk/src/react/-internal-/interfaces/reactelement/)

## Properties

[Section titled “Properties”](#properties)

### children

[Section titled “children”](#children)

```ts
children: ReactNode;
```

Defined in: node\_modules/@types/react/index.d.ts:397

***

### key

[Section titled “key”](#key)

```ts
key: string | null;
```

Defined in: node\_modules/@types/react/index.d.ts:331

#### Inherited from

[Section titled “Inherited from”](#inherited-from)

[`ReactElement`](/api/sdk/src/react/-internal-/interfaces/reactelement/).[`key`](/api/sdk/src/react/-internal-/interfaces/reactelement/#key)

***

### props

[Section titled “props”](#props)

```ts
props: unknown;
```

Defined in: node\_modules/@types/react/index.d.ts:330

#### Inherited from

[Section titled “Inherited from”](#inherited-from-1)

[`ReactElement`](/api/sdk/src/react/-internal-/interfaces/reactelement/).[`props`](/api/sdk/src/react/-internal-/interfaces/reactelement/#props)

***

### type

[Section titled “type”](#type)

```ts
type:
  | string
| JSXElementConstructor<any>;
```

Defined in: node\_modules/@types/react/index.d.ts:329

#### Inherited from

[Section titled “Inherited from”](#inherited-from-2)

[`ReactElement`](/api/sdk/src/react/-internal-/interfaces/reactelement/).[`type`](/api/sdk/src/react/-internal-/interfaces/reactelement/#type)

# Consumer

```ts
type Consumer<T> = ExoticComponent<ConsumerProps<T>>;
```

Defined in: node\_modules/@types/react/index.d.ts:659

The old way to read context, before useContext existed.

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `T`            |

## See

[Section titled “See”](#see)

[React Docs](https://react.dev/reference/react/createContext#consumer)

## Example

[Section titled “Example”](#example)

```tsx
import { UserContext } from './user-context';


function Avatar() {
  return (
    <UserContext.Consumer>
      {user => <img src={user.profileImage} alt={user.name} />}
    </UserContext.Consumer>
  );
}
```

# IteratorResult

```ts
type IteratorResult<T, TReturn> =
  | IteratorYieldResult<T>
| IteratorReturnResult<TReturn>;
```

Defined in: node\_modules/typescript/lib/lib.es2015.iterable.d.ts:37

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Default type |
| -------------- | ------------ |
| `T`            | -            |
| `TReturn`      | `any`        |

# JSXElementConstructor

```ts
type JSXElementConstructor<P> =
  | ((props) =>
  | ReactNode
  | Promise<ReactNode>)
  | ((props, context) => Component<any, any>);
```

Defined in: node\_modules/@types/react/index.d.ts:134

Represents any user-defined component, either as a function or a class.

Similar to ComponentType, but without extra properties like FunctionComponent.defaultProps defaultProps.

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter | Description                      |
| -------------- | -------------------------------- |
| `P`            | The props the component accepts. |

# Pick

```ts
type Pick<T, K> = { [P in K]: T[P] };
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1604

From T, pick a set of properties whose keys are in the union K

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter          |
| ----------------------- |
| `T`                     |
| `K` *extends* keyof `T` |

# Provider

```ts
type Provider<T> = ProviderExoticComponent<ProviderProps<T>>;
```

Defined in: node\_modules/@types/react/index.d.ts:638

Wraps your components to specify the value of this context for all components inside.

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `T`            |

## See

[Section titled “See”](#see)

[React Docs](https://react.dev/reference/react/createContext#provider)

## Example

[Section titled “Example”](#example)

```tsx
import { createContext } from 'react';


const ThemeContext = createContext('light');


function App() {
  return (
    <ThemeContext.Provider value="dark">
      <Toolbar />
    </ThemeContext.Provider>
  );
}
```

# ReactNode

```ts
type ReactNode =
  | ReactElement
  | string
  | number
  | bigint
  | Iterable<ReactNode>
  | ReactPortal
  | boolean
  | null
  | undefined
  | DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_REACT_NODES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_REACT_NODES]
| Promise<AwaitedReactNode>;
```

Defined in: node\_modules/@types/react/index.d.ts:436

Represents all of the things React can render.

Where [ReactElement](/api/sdk/src/react/-internal-/interfaces/reactelement/) only represents JSX, `ReactNode` represents everything that can be rendered.

## See

[Section titled “See”](#see)

[React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/react-types/reactnode/)

## Examples

[Section titled “Examples”](#examples)

```tsx
// Typing children
type Props = { children: ReactNode }


const Component = ({ children }: Props) => <div>{children}</div>


<Component>hello</Component>
```

```tsx
// Typing a custom element
type Props = { customElement: ReactNode }


const Component = ({ customElement }: Props) => <div>{customElement}</div>


<Component customElement={<div>hello</div>} />
```

# Readonly

```ts
type Readonly<T> = { readonly [P in keyof T]: T[P] };
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1597

Make all properties in T readonly

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `T`            |

# SlotState

```ts
type SlotState = {
  error: Error | null;
  isLoading: boolean;
  resolution: AssetDTO | null;
  url: string | null;
};
```

Defined in: packages/sdk/src/react/index.ts:39

## Properties

[Section titled “Properties”](#properties)

### error

[Section titled “error”](#error)

```ts
error: Error | null;
```

Defined in: packages/sdk/src/react/index.ts:45

***

### isLoading

[Section titled “isLoading”](#isloading)

```ts
isLoading: boolean;
```

Defined in: packages/sdk/src/react/index.ts:44

***

### resolution

[Section titled “resolution”](#resolution)

```ts
resolution: AssetDTO | null;
```

Defined in: packages/sdk/src/react/index.ts:41

Resolved DTO (`null` while loading or unbound).

***

### url

[Section titled “url”](#url)

```ts
url: string | null;
```

Defined in: packages/sdk/src/react/index.ts:43

Convenience: the CDN URL, when resolved.

# AquienpzProvider

```ts
function AquienpzProvider(props): ReactNode;
```

Defined in: packages/sdk/src/react/index.ts:23

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter        | Type                                                                                                                                                      |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `props`          | { `children`: [`ReactNode`](/api/sdk/src/react/-internal-/type-aliases/reactnode/); `client`: [`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/); } |
| `props.children` | [`ReactNode`](/api/sdk/src/react/-internal-/type-aliases/reactnode/)                                                                                      |
| `props.client`   | [`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/)                                                                                                  |

## Returns

[Section titled “Returns”](#returns)

[`ReactNode`](/api/sdk/src/react/-internal-/type-aliases/reactnode/)

# useAquienpzClient

```ts
function useAquienpzClient(): AquienpzClient;
```

Defined in: packages/sdk/src/react/index.ts:27

## Returns

[Section titled “Returns”](#returns)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/)

# useSlot

```ts
function useSlot(slotKey, options?): SlotState;
```

Defined in: packages/sdk/src/react/index.ts:54

Subscribe to a single slot. Re-resolves when the key changes or the cache is invalidated. Returns `{resolution, url, isLoading, error}`.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                 |
| --------- | -------------------- |
| `slotKey` | `string`             |
| `options` | `ResolveSlotOptions` |

## Returns

[Section titled “Returns”](#returns)

[`SlotState`](/api/sdk/src/react/-internal-/type-aliases/slotstate/)

# useSlots

```ts
function useSlots(slotKeys, options?): {
  error: Error | null;
  isLoading: boolean;
  resolutions: Record<string, AssetDTO>;
};
```

Defined in: packages/sdk/src/react/index.ts:89

Bulk version — fetches N keys in one round-trip. Returns a map keyed by slot key. Pass a STABLE array reference (memoize with useMemo) to avoid re-fetches on every render.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter  | Type                 |
| ---------- | -------------------- |
| `slotKeys` | `string`\[]          |
| `options`  | `ResolveSlotOptions` |

## Returns

[Section titled “Returns”](#returns)

```ts
{
  error: Error | null;
  isLoading: boolean;
  resolutions: Record<string, AssetDTO>;
}
```

### error

[Section titled “error”](#error)

```ts
error: Error | null;
```

### isLoading

[Section titled “isLoading”](#isloading)

```ts
isLoading: boolean;
```

### resolutions

[Section titled “resolutions”](#resolutions)

```ts
resolutions: Record<string, AssetDTO>;
```

# AquienpzClient

Defined in: packages/sdk/src/server/index.ts:72

Server-safe `AquienpzClient` — same runtime as the root class, but the constructor type enforces `apiKey` so misconfiguration is a TS build error, not a runtime 401.

## Extends

[Section titled “Extends”](#extends)

* [`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/)

## Constructors

[Section titled “Constructors”](#constructors)

### Constructor

[Section titled “Constructor”](#constructor)

```ts
new AquienpzClient(opts): AquienpzClient;
```

Defined in: packages/sdk/src/server/index.ts:73

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                           |
| --------- | ------------------------------------------------------------------------------ |
| `opts`    | [`ServerClientOptions`](/api/sdk/src/server/type-aliases/serverclientoptions/) |

#### Returns

[Section titled “Returns”](#returns)

`AquienpzClient`

#### Overrides

[Section titled “Overrides”](#overrides)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`constructor`](/api/sdk/src/classes/aquienpzclient/#constructor)

## Properties

[Section titled “Properties”](#properties)

### assets

[Section titled “assets”](#assets)

```ts
readonly assets: AssetsApi;
```

Defined in: packages/sdk/src/index.ts:1074

#### Inherited from

[Section titled “Inherited from”](#inherited-from)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`assets`](/api/sdk/src/classes/aquienpzclient/#assets)

***

### opts

[Section titled “opts”](#opts)

```ts
readonly opts: AquienpzClientOptions;
```

Defined in: packages/sdk/src/index.ts:1081

Effective options — read-only. Exposed so the `/web` and `/expo` subpaths can inherit endpoint / apiKey / tenant scope from the configured client without re-passing them per call site.

#### Inherited from

[Section titled “Inherited from”](#inherited-from-1)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`opts`](/api/sdk/src/classes/aquienpzclient/#opts)

***

### slots

[Section titled “slots”](#slots)

```ts
readonly slots: SlotsApi;
```

Defined in: packages/sdk/src/index.ts:1073

#### Inherited from

[Section titled “Inherited from”](#inherited-from-2)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`slots`](/api/sdk/src/classes/aquienpzclient/#slots)

***

### usage

[Section titled “usage”](#usage)

```ts
readonly usage: UsageApi;
```

Defined in: packages/sdk/src/index.ts:1075

#### Inherited from

[Section titled “Inherited from”](#inherited-from-3)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`usage`](/api/sdk/src/classes/aquienpzclient/#usage)

## Accessors

[Section titled “Accessors”](#accessors)

### tenantSegment

[Section titled “tenantSegment”](#tenantsegment)

#### Get Signature

[Section titled “Get Signature”](#get-signature)

```ts
get tenantSegment(): string;
```

Defined in: packages/sdk/src/index.ts:1102

Tenant id as base36 path segment (e.g. tenantId=4 → “4/v/”).

##### Returns

[Section titled “Returns”](#returns-1)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-4)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`tenantSegment`](/api/sdk/src/classes/aquienpzclient/#tenantsegment)

## Methods

[Section titled “Methods”](#methods)

### srcSetFor()

[Section titled “srcSetFor()”](#srcsetfor)

```ts
srcSetFor(asset): string;
```

Defined in: packages/sdk/src/index.ts:1112

Build a responsive srcSet across the available image presets.

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter | Type                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"` \| `"presets"`> |

#### Returns

[Section titled “Returns”](#returns-2)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-5)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`srcSetFor`](/api/sdk/src/classes/aquienpzclient/#srcsetfor)

***

### streamingUrl()

[Section titled “streamingUrl()”](#streamingurl)

```ts
streamingUrl(asset, opts?): string;
```

Defined in: packages/sdk/src/index.ts:1287

Build the HLS master playlist URL for a VIDEO asset (Phase 5).

Returns `<cdn>/t/format=hls(,start=…,duration=…)/<sha>.m3u8`. Pass to an HLS-aware player:

\<video src={aq.streamingUrl(asset)} controls playsInline // Video.js v10’s @videojs/http-streaming ships native HLS — // no plugin needed. />

On the first request the server returns **202 Accepted** while a Cloud Run Job builds the multi-rung ladder (typically 1-3 min for a 90 s source — five rungs of 240p/360p/480p/720p/1080p @ AAC). Subsequent requests hit the cache → **302** to the master.m3u8.

Supports `start` + `duration` to ladder a sub-clip. Other DSL params (width, height, fit) are ignored on the HLS path because the rungs determine resolution.

#### Parameters

[Section titled “Parameters”](#parameters-2)

| Parameter | Type                                                                                                                         |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`>       |
| `opts`    | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"format"`> |

#### Returns

[Section titled “Returns”](#returns-3)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-6)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`streamingUrl`](/api/sdk/src/classes/aquienpzclient/#streamingurl)

***

### transform()

[Section titled “transform()”](#transform)

#### Call Signature

[Section titled “Call Signature”](#call-signature)

```ts
transform(asset, opts?): string;
```

Defined in: packages/sdk/src/index.ts:1145

Build an on-the-fly transform URL — `<cdn>/t/<dsl>/<sha>.<ext>`.

## URL CONVENTION — transforms are NOT tenant-prefixed (variants are)

[Section titled “URL CONVENTION — transforms are NOT tenant-prefixed (variants are)”](#url-convention--transforms-are-not-tenant-prefixed-variants-are)

Two distinct delivery paths, by design:

* **Variants / presets** (`urlFor`, `srcSetFor`, upload `cdnUrl`): `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>` ← tenant-scoped (e.g. `/4/v/<sha>-lg.webp`)
* **On-the-fly transforms** (`transform`, `transformSrcSet`): `<cdn>/t/<dsl>/<sha>.<ext>` ← GLOBAL, no tenant segment (`/t/...`) The transform service is content-addressed by sha + resizes from the source on demand, so it needs no tenant in the path. Prefixing a transform URL with `/<tenant>/t/...` 404s. Consumers that build URLs by hand must NOT add the tenant segment to `/t/` URLs.

Returns the canonical `lg` variant URL when called with empty options, so callers can swap `urlFor()` for `transform()` without thinking.

URLs with the same params in different order produce the same R2 cache entry (the server canonicalizes both sides). Safe to use as stable cache keys.

\<Image src={aq.transform(asset, { width: 1280 })} srcSet={aq.transformSrcSet(asset, \[640, 960, 1280, 1920])} sizes=“(max-width: 768px) 100vw, 50vw” />

##### Parameters

[Section titled “Parameters”](#parameters-3)

| Parameter | Type                                                                                                                   |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `opts?`   | `any`                                                                                                                  |

##### Returns

[Section titled “Returns”](#returns-4)

`string`

##### See

[Section titled “See”](#see)

[TransformOptions](/api/sdk/src/type-aliases/assetdto/) for the full param matrix.

##### Inherited from

[Section titled “Inherited from”](#inherited-from-7)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transform`](/api/sdk/src/classes/aquienpzclient/#transform)

#### Call Signature

[Section titled “Call Signature”](#call-signature-1)

```ts
transform(
   asset,
   opts,
signOpts): Promise<string>;
```

Defined in: packages/sdk/src/index.ts:1149

Build an on-the-fly transform URL — `<cdn>/t/<dsl>/<sha>.<ext>`.

## URL CONVENTION — transforms are NOT tenant-prefixed (variants are)

[Section titled “URL CONVENTION — transforms are NOT tenant-prefixed (variants are)”](#url-convention--transforms-are-not-tenant-prefixed-variants-are-1)

Two distinct delivery paths, by design:

* **Variants / presets** (`urlFor`, `srcSetFor`, upload `cdnUrl`): `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>` ← tenant-scoped (e.g. `/4/v/<sha>-lg.webp`)
* **On-the-fly transforms** (`transform`, `transformSrcSet`): `<cdn>/t/<dsl>/<sha>.<ext>` ← GLOBAL, no tenant segment (`/t/...`) The transform service is content-addressed by sha + resizes from the source on demand, so it needs no tenant in the path. Prefixing a transform URL with `/<tenant>/t/...` 404s. Consumers that build URLs by hand must NOT add the tenant segment to `/t/` URLs.

Returns the canonical `lg` variant URL when called with empty options, so callers can swap `urlFor()` for `transform()` without thinking.

URLs with the same params in different order produce the same R2 cache entry (the server canonicalizes both sides). Safe to use as stable cache keys.

\<Image src={aq.transform(asset, { width: 1280 })} srcSet={aq.transformSrcSet(asset, \[640, 960, 1280, 1920])} sizes=“(max-width: 768px) 100vw, 50vw” />

##### Parameters

[Section titled “Parameters”](#parameters-4)

| Parameter       | Type                                                                                                                   |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`         | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `opts`          | `SignedTransformOptions`                                                                                               |
| `signOpts`      | { `sign`: `true`; }                                                                                                    |
| `signOpts.sign` | `true`                                                                                                                 |

##### Returns

[Section titled “Returns”](#returns-5)

`Promise`<`string`>

##### See

[Section titled “See”](#see-1)

[TransformOptions](/api/sdk/src/type-aliases/assetdto/) for the full param matrix.

##### Inherited from

[Section titled “Inherited from”](#inherited-from-8)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transform`](/api/sdk/src/classes/aquienpzclient/#transform)

***

### transformSrcSet()

[Section titled “transformSrcSet()”](#transformsrcset)

#### Call Signature

[Section titled “Call Signature”](#call-signature-2)

```ts
transformSrcSet(
   asset,
   widths,
   extraOpts?): string;
```

Defined in: packages/sdk/src/index.ts:1189

Build a responsive `srcSet` string. One transform URL per width; all other options apply to every URL.

Pass `{ sign: true }` to return signed URLs (async). Without it, the call stays synchronous as before.

##### Parameters

[Section titled “Parameters”](#parameters-5)

| Parameter    | Type                                                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`      | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `widths`     | `number`\[]                                                                                                            |
| `extraOpts?` | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<`TransformOptions`, `"width"`>                           |

##### Returns

[Section titled “Returns”](#returns-6)

`string`

##### Inherited from

[Section titled “Inherited from”](#inherited-from-9)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transformSrcSet`](/api/sdk/src/classes/aquienpzclient/#transformsrcset)

#### Call Signature

[Section titled “Call Signature”](#call-signature-3)

```ts
transformSrcSet(
   asset,
   widths,
   extraOpts,
signOpts): Promise<string>;
```

Defined in: packages/sdk/src/index.ts:1194

Build a responsive `srcSet` string. One transform URL per width; all other options apply to every URL.

Pass `{ sign: true }` to return signed URLs (async). Without it, the call stays synchronous as before.

##### Parameters

[Section titled “Parameters”](#parameters-6)

| Parameter       | Type                                                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `asset`         | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`>      |
| `widths`        | `number`\[]                                                                                                                 |
| `extraOpts`     | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"width"`> |
| `signOpts`      | { `sign`: `true`; }                                                                                                         |
| `signOpts.sign` | `true`                                                                                                                      |

##### Returns

[Section titled “Returns”](#returns-7)

`Promise`<`string`>

##### Inherited from

[Section titled “Inherited from”](#inherited-from-10)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transformSrcSet`](/api/sdk/src/classes/aquienpzclient/#transformsrcset)

***

### transformVideo()

[Section titled “transformVideo()”](#transformvideo)

```ts
transformVideo(asset, opts?): string;
```

Defined in: packages/sdk/src/index.ts:1258

Build an on-the-fly VIDEO transform URL — Phase 4.

Same DSL shape as `transform()` but the URL has a `.mp4` (default) or `.webm` extension and the server routes the request to a Cloud Run Job for ffmpeg encoding (vs the inline sharp pipeline for images).

On the first request the route returns **202 Accepted** with `Retry-After: 10` while the Job 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.

const url = aq.transformVideo(asset, { width: 1080, height: 1920, fit: “cover”, start: 0, duration: 15, }); // Pass to Video.js / [; on the first load it // gets 202 + body.outputUrl; subsequent loads hit cache → 302.]({url})

Video-specific DSL params:

* `start` (seconds, decimal OK)
* `duration` (seconds, 1..300)
* `format`: “mp4” (default) or “webm”

The other params (`width`, `height`, `fit`) work identically to image transforms. `gravity`, `quality`, `effect`, `dpr` are accepted by the DSL but currently ignored on the video path.

#### Parameters

[Section titled “Parameters”](#parameters-7)

| Parameter | Type                                                                                                                   |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `opts`    | `TransformOptions`                                                                                                     |

#### Returns

[Section titled “Returns”](#returns-8)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-11)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transformVideo`](/api/sdk/src/classes/aquienpzclient/#transformvideo)

***

### upload()

[Section titled “upload()”](#upload)

```ts
upload(input, opts?): Promise<UploadResult>;
```

Defined in: packages/sdk/src/index.ts:1348

Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-R2 PUT** → `/assets/process` → wait until the asset is ready.

⚠️ `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”.

#### Parameters

[Section titled “Parameters”](#parameters-8)

| Parameter | Type                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------- |
| `input`   | \| `File` \| `Blob` \| `Uint8Array`<[`ArrayBufferLike`](/api/sdk/src/web/-internal-/type-aliases/arraybufferlike/)> |
| `opts`    | [`UploadOptions`](/api/sdk/src/type-aliases/uploadoptions/)                                                         |

#### Returns

[Section titled “Returns”](#returns-9)

`Promise`<[`UploadResult`](/api/sdk/src/type-aliases/uploadresult/)>

#### Examples

[Section titled “Examples”](#examples)

**Deliver an image on a site (the responsive ladder)**

```ts
import { AquienpzClient } from "@aquienpz/sdk/server";


const aq = new AquienpzClient({ endpoint, apiKey, tenantCode, tenantId });
const { assetId, sha256 } = await aq.upload(file, {
  fileName: file.name,
  presets: ["thumb", "sm", "md", "lg"],
});
```

**ARCHIVE a file — you must ask for \`original\`**

```ts
await aq.upload(bytes, {
  fileName: "contrato.pdf",
  contentType: "application/pdf",
  presets: ["original"],          // without this the bytes are unrecoverable
});
```

**Raw bytes need an explicit MIME**

```ts
await aq.upload(bytes, { fileName: "track.mp3", contentType: "audio/mpeg" });
// Without either, it stores as kind:"other" — no variants, and regenerate() is unsupported.
```

**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.
await aq.upload(clip, { fileName: "tour.mp4", presets: ["poster", "video"] });


// Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost Job time
// and permanent R2 objects that nothing else reads.
```

#### Inherited from

[Section titled “Inherited from”](#inherited-from-12)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`upload`](/api/sdk/src/classes/aquienpzclient/#upload)

***

### urlFor()

[Section titled “urlFor()”](#urlfor)

```ts
urlFor(asset, preset?): string;
```

Defined in: packages/sdk/src/index.ts:1107

Build the canonical CDN URL deterministically from sha + preset.

#### Parameters

[Section titled “Parameters”](#parameters-9)

| Parameter | Type                                                                                                                   | Default value |
| --------- | ---------------------------------------------------------------------------------------------------------------------- | ------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> | `undefined`   |
| `preset`  | `VariantPreset`                                                                                                        | `"lg"`        |

#### Returns

[Section titled “Returns”](#returns-10)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-13)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`urlFor`](/api/sdk/src/classes/aquienpzclient/#urlfor)

# ServerClientOptions

```ts
type ServerClientOptions = Required<Pick<AquienpzClientOptions, "endpoint" | "apiKey" | "tenantCode" | "tenantId">> & Pick<AquienpzClientOptions, "cdnBase" | "signingKey">;
```

Defined in: packages/sdk/src/server/index.ts:62

Server-side constructor options — `apiKey` is REQUIRED here. Use this type whenever you build a client behind a process boundary (Node, Bun, Cloud Run, Vercel Functions, edge runtimes, BFFs).

const aq = new AquienpzClient({ endpoint: process.env.ASSET\_MANAGER\_URL!, apiKey: process.env.ASSET\_MANAGER\_API\_KEY!, tenantCode: “realtyone-cr”, tenantId: 1, });

# AquienpzClientOptions

```ts
type AquienpzClientOptions = {
  apiKey?: string;
  cdnBase?: string;
  endpoint: string;
  headers?: Record<string, string>;
  signingKey?: string;
  tenantCode: string;
  tenantId: number;
};
```

Defined in: packages/sdk/src/index.ts:78

Permissive constructor options for the root `AquienpzClient`.

App code should NOT import this type directly — prefer the strict variants from the subpaths:

* `WebClientOptions` from `@aquienpz/sdk/web` (no `apiKey`)
* `ServerClientOptions` from `@aquienpz/sdk/server` (`apiKey` required)

This root type is the union both modes resolve to; the underlying class accepts both shapes so subpath wrappers can extend without duplication.

## Properties

[Section titled “Properties”](#properties)

### apiKey?

[Section titled “apiKey?”](#apikey)

```ts
optional apiKey?: string;
```

Defined in: packages/sdk/src/index.ts:93

Better Auth API key with the `amk_rt_*` prefix.

**Server-only.** Omit when constructing from `@aquienpz/sdk/web` — your BFF / route handler injects the bearer header in proxy mode.

***

### cdnBase?

[Section titled “cdnBase?”](#cdnbase)

```ts
optional cdnBase?: string;
```

Defined in: packages/sdk/src/index.ts:108

Override the public CDN base. Defaults to `https://8ok.uk`.

***

### endpoint

[Section titled “endpoint”](#endpoint)

```ts
endpoint: string;
```

Defined in: packages/sdk/src/index.ts:86

Base URL of the aquienpz asset-manager (Cloud Run service URL).

May be relative (e.g. `/api/am`) ONLY in browser contexts where the SDK resolves it against `window.location.origin`. Node/Bun consumers must always pass an absolute URL.

***

### headers?

[Section titled “headers?”](#headers)

```ts
optional headers?: Record<string, string>;
```

Defined in: packages/sdk/src/index.ts:102

Extra headers merged into every request. The documented way for mobile/Expo clients to authenticate a BFF that gates on the Better Auth session: they can’t send cookies automatically, so they pass `{ Cookie: authClient.getCookie() }` here (see Better Auth Expo docs, “Making Authenticated Requests to Your Server”). Web/server consumers omit this — browsers attach the same-origin cookie and servers pass `apiKey`.

***

### signingKey?

[Section titled “signingKey?”](#signingkey)

```ts
optional signingKey?: string;
```

Defined in: packages/sdk/src/index.ts:118

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 server-side only** — do not ship in `NEXT_PUBLIC_*` env vars. Sign URLs from a BFF route handler, or pre-sign at build time.

***

### tenantCode

[Section titled “tenantCode”](#tenantcode)

```ts
tenantCode: string;
```

Defined in: packages/sdk/src/index.ts:104

Tenant code — sent as `X-Tenant-Code` (log-only). Authoritative scope is the key’s metadata.tenantId.

***

### tenantId

[Section titled “tenantId”](#tenantid)

```ts
tenantId: number;
```

Defined in: packages/sdk/src/index.ts:106

Numeric tenant id — used to build tenant-prefixed CDN URLs `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>`.

# AssetDTO

```ts
type AssetDTO = any;
```

# ComposeMarketingComposition

```ts
type ComposeMarketingComposition = {
  audioTrack?: {
     url: string;
  };
  finalDurationSec?: number;
  transition?: "cut" | "fade";
};
```

Defined in: packages/sdk/src/index.ts:453

## Properties

[Section titled “Properties”](#properties)

### audioTrack?

[Section titled “audioTrack?”](#audiotrack)

```ts
optional audioTrack?: {
  url: string;
};
```

Defined in: packages/sdk/src/index.ts:457

Optional audio track to mix on top of the final composition.

#### url

[Section titled “url”](#url)

```ts
url: string;
```

***

### finalDurationSec?

[Section titled “finalDurationSec?”](#finaldurationsec)

```ts
optional finalDurationSec?: number;
```

Defined in: packages/sdk/src/index.ts:459

Final composition length in seconds (server may clamp).

***

### transition?

[Section titled “transition?”](#transition)

```ts
optional transition?: "cut" | "fade";
```

Defined in: packages/sdk/src/index.ts:455

Transition between consecutive segments. Default `"cut"`.

# ComposeMarketingOptions

```ts
type ComposeMarketingOptions = {
  composition?: ComposeMarketingComposition;
  marketingKitId: string;
  segments: ComposeMarketingSegment[];
};
```

Defined in: packages/sdk/src/index.ts:462

## Properties

[Section titled “Properties”](#properties)

### composition?

[Section titled “composition?”](#composition)

```ts
optional composition?: ComposeMarketingComposition;
```

Defined in: packages/sdk/src/index.ts:468

Optional composition-level knobs (transitions, audio, duration).

***

### marketingKitId

[Section titled “marketingKitId”](#marketingkitid)

```ts
marketingKitId: string;
```

Defined in: packages/sdk/src/index.ts:464

Marketing-kit id this composition belongs to (server uses it for naming + dedup).

***

### segments

[Section titled “segments”](#segments)

```ts
segments: ComposeMarketingSegment[];
```

Defined in: packages/sdk/src/index.ts:466

Ordered clip segments to stitch.

# ComposeMarketingResult

```ts
type ComposeMarketingResult = {
  assetId: string;
  status: "processing" | "ready" | "failed";
};
```

Defined in: packages/sdk/src/index.ts:471

## Properties

[Section titled “Properties”](#properties)

### assetId

[Section titled “assetId”](#assetid)

```ts
assetId: string;
```

Defined in: packages/sdk/src/index.ts:473

Aquienpz asset id of the in-flight composition. Poll `aq.assets.waitReady(id)`.

***

### status

[Section titled “status”](#status)

```ts
status: "processing" | "ready" | "failed";
```

Defined in: packages/sdk/src/index.ts:475

Asset status at dispatch time — usually `"processing"`.

# ComposeMarketingSegment

```ts
type ComposeMarketingSegment = {
  durationSec?: number;
  sourceUrl: string;
};
```

Defined in: packages/sdk/src/index.ts:446

Input shape accepted by `aq.assets.composeMarketing(...)`.

## Properties

[Section titled “Properties”](#properties)

### durationSec?

[Section titled “durationSec?”](#durationsec)

```ts
optional durationSec?: number;
```

Defined in: packages/sdk/src/index.ts:450

Optional clip duration in seconds (cap for that segment).

***

### sourceUrl

[Section titled “sourceUrl”](#sourceurl)

```ts
sourceUrl: string;
```

Defined in: packages/sdk/src/index.ts:448

Public URL of the source clip (typically a `/t/.../video.mp4` transform).

# CompressOptions

```ts
type CompressOptions = {
  convertHeic?: boolean;
  convertSize?: number;
  keepOriginalDimensions?: boolean;
  maxHeight?: number;
  maxWidth?: number;
  mimeType?: "image/jpeg" | "image/webp";
  onProgress?: (stage) => void;
  quality?: number;
  strict?: boolean;
};
```

Defined in: packages/sdk/src/index.ts:834

Subset of compressorjs options exposed through the SDK. Re-imported here to avoid a hard import dependency on `./web` from this top-level module (the /web subpath uses browser-only APIs). The runtime `compress` implementation is lazy-loaded so Node/Bun callers don’t pay the bundle cost — see `aq.upload` below.

## Properties

[Section titled “Properties”](#properties)

### convertHeic?

[Section titled “convertHeic?”](#convertheic)

```ts
optional convertHeic?: boolean;
```

Defined in: packages/sdk/src/index.ts:842

***

### convertSize?

[Section titled “convertSize?”](#convertsize)

```ts
optional convertSize?: number;
```

Defined in: packages/sdk/src/index.ts:839

***

### keepOriginalDimensions?

[Section titled “keepOriginalDimensions?”](#keeporiginaldimensions)

```ts
optional keepOriginalDimensions?: boolean;
```

Defined in: packages/sdk/src/index.ts:841

***

### maxHeight?

[Section titled “maxHeight?”](#maxheight)

```ts
optional maxHeight?: number;
```

Defined in: packages/sdk/src/index.ts:838

***

### maxWidth?

[Section titled “maxWidth?”](#maxwidth)

```ts
optional maxWidth?: number;
```

Defined in: packages/sdk/src/index.ts:837

***

### mimeType?

[Section titled “mimeType?”](#mimetype)

```ts
optional mimeType?: "image/jpeg" | "image/webp";
```

Defined in: packages/sdk/src/index.ts:836

***

### onProgress?

[Section titled “onProgress?”](#onprogress)

```ts
optional onProgress?: (stage) => void;
```

Defined in: packages/sdk/src/index.ts:843

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                      |
| --------- | ------------------------------------------------------------------------- |
| `stage`   | `"convertingHeic"` \| `"compressing"` \| `"compressingKeepingDimensions"` |

#### Returns

[Section titled “Returns”](#returns)

`void`

***

### quality?

[Section titled “quality?”](#quality)

```ts
optional quality?: number;
```

Defined in: packages/sdk/src/index.ts:835

***

### strict?

[Section titled “strict?”](#strict)

```ts
optional strict?: boolean;
```

Defined in: packages/sdk/src/index.ts:840

# PresignUploadUrlOptions

```ts
type PresignUploadUrlOptions = {
  bytes: number;
  clientOriginalBytes?: number;
  fileName: string;
  mime: string;
  presets?: AssetDTO[];
  sha256: string;
  video?: UploadVideoOptions;
};
```

Defined in: packages/sdk/src/index.ts:421

Input shape accepted by `aq.assets.presignUploadUrl(...)`.

## Properties

[Section titled “Properties”](#properties)

### bytes

[Section titled “bytes”](#bytes)

```ts
bytes: number;
```

Defined in: packages/sdk/src/index.ts:427

Byte length of the upload payload.

***

### clientOriginalBytes?

[Section titled “clientOriginalBytes?”](#clientoriginalbytes)

```ts
optional clientOriginalBytes?: number;
```

Defined in: packages/sdk/src/index.ts:440

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`.

***

### fileName

[Section titled “fileName”](#filename)

```ts
fileName: string;
```

Defined in: packages/sdk/src/index.ts:429

Suggested file name; surfaces in admin dashboards + extension fallback.

***

### mime

[Section titled “mime”](#mime)

```ts
mime: string;
```

Defined in: packages/sdk/src/index.ts:425

MIME type of the bytes (e.g. `image/jpeg`, `video/mp4`).

***

### presets?

[Section titled “presets?”](#presets)

```ts
optional presets?: AssetDTO[];
```

Defined in: packages/sdk/src/index.ts:434

Variant ladder to generate after `/assets/process`. Defaults to `["original"]` server-side when omitted — same contract as `aq.upload`.

***

### sha256

[Section titled “sha256”](#sha256)

```ts
sha256: string;
```

Defined in: packages/sdk/src/index.ts:423

Full sha256 (64 hex) of the bytes that will be PUT to R2.

***

### video?

[Section titled “video?”](#video)

```ts
optional video?: UploadVideoOptions;
```

Defined in: packages/sdk/src/index.ts:442

VIDEO-only delivery knobs forwarded into `/assets/process`. See [UploadVideoOptions](/api/sdk/src/type-aliases/uploadvideooptions/).

# RegenerateResult

```ts
type RegenerateResult =
  | {
  kind: "image";
  newVariants: AssetDTO[];
  ok: true;
  sourceUsed: AssetDTO | "raw";
  variants: AssetDTO[];
}
  | {
  dispatch: unknown;
  kind: "video";
  ok: true;
  regenerated: string[] | "default";
};
```

Defined in: packages/sdk/src/index.ts:353

Returned by `aq.assets.regenerate(...)`. The shape varies by kind — images return immediately with the merged variant list; videos return a dispatch handle (the actual transcode runs in a Cloud Run Job and finishes async).

## Union Members

[Section titled “Union Members”](#union-members)

### Type Literal

[Section titled “Type Literal”](#type-literal)

```ts
{
  kind: "image";
  newVariants: AssetDTO[];
  ok: true;
  sourceUsed: AssetDTO | "raw";
  variants: AssetDTO[];
}
```

#### kind

[Section titled “kind”](#kind)

```ts
kind: "image";
```

#### newVariants

[Section titled “newVariants”](#newvariants)

```ts
newVariants: AssetDTO[];
```

Presets newly written this run. Useful for showing “added X”.

#### ok

[Section titled “ok”](#ok)

```ts
ok: true;
```

#### sourceUsed

[Section titled “sourceUsed”](#sourceused)

```ts
sourceUsed: AssetDTO | "raw";
```

Which source the server read to derive the new variants:

* `"original"` / `"raw"` → lossless source bytes (best)
* `"xl"` / `"lg"` / `"md"` / `"sm"` / `"thumb"` → a previously encoded WebP variant was used as the source. Output is re-encoded WebP — fine for thumb/sm from lg, lossier when working from already-small sources.

The no-upscale clamp still applies: deriving `lg` (1920) from a 640 `sm` source produces a 640-side `lg` variant, not a stretched 1920.

#### variants

[Section titled “variants”](#variants)

```ts
variants: AssetDTO[];
```

Full variant set after the merge.

***

### Type Literal

[Section titled “Type Literal”](#type-literal-1)

```ts
{
  dispatch: unknown;
  kind: "video";
  ok: true;
  regenerated: string[] | "default";
}
```

# SlotHistoryEntry

```ts
type SlotHistoryEntry = {
  action: "bind" | "unbind" | "restore";
  asset: AssetDTO | null;
  assetId: string | null;
  description: string | null;
  id: string;
  preset: AssetDTO | null;
  updatedAt: string;
  updatedBy: string | null;
};
```

Defined in: packages/sdk/src/index.ts:971

## Properties

[Section titled “Properties”](#properties)

### action

[Section titled “action”](#action)

```ts
action: "bind" | "unbind" | "restore";
```

Defined in: packages/sdk/src/index.ts:973

***

### asset

[Section titled “asset”](#asset)

```ts
asset: AssetDTO | null;
```

Defined in: packages/sdk/src/index.ts:980

Resolved DTO when the asset still exists; `null` after delete / 404.

***

### assetId

[Section titled “assetId”](#assetid)

```ts
assetId: string | null;
```

Defined in: packages/sdk/src/index.ts:978

***

### description

[Section titled “description”](#description)

```ts
description: string | null;
```

Defined in: packages/sdk/src/index.ts:975

***

### id

[Section titled “id”](#id)

```ts
id: string;
```

Defined in: packages/sdk/src/index.ts:972

***

### preset

[Section titled “preset”](#preset)

```ts
preset: AssetDTO | null;
```

Defined in: packages/sdk/src/index.ts:974

***

### updatedAt

[Section titled “updatedAt”](#updatedat)

```ts
updatedAt: string;
```

Defined in: packages/sdk/src/index.ts:976

***

### updatedBy

[Section titled “updatedBy”](#updatedby)

```ts
updatedBy: string | null;
```

Defined in: packages/sdk/src/index.ts:977

# UploadOptions

```ts
type UploadOptions = {
  compress?:   | boolean
     | CompressOptions;
  contentType?: string;
  fileName?: string;
  presets?: AssetDTO[];
  sha256?: string;
  timeoutMs?: number;
  video?: UploadVideoOptions;
};
```

Defined in: packages/sdk/src/index.ts:848

## Properties

[Section titled “Properties”](#properties)

### compress?

[Section titled “compress?”](#compress)

```ts
optional compress?:
  | boolean
  | CompressOptions;
```

Defined in: packages/sdk/src/index.ts:883

Client-side compression before upload. Saves user bandwidth — typical 5–10× reduction for raw phone photos. Browser-only; in Node/Bun this silently no-ops with a console.warn and the raw bytes upload as-is.

* `true` → use SDK `DEFAULT_COMPRESSION_OPTIONS` (webapp-tuned)
* `CompressOptions` → merge over defaults
* `false` / omit → no compression (current default behavior)

Implementation is lazy-imported from `@aquienpz/sdk/web` so callers that never set `compress` don’t pay the compressorjs + heic2any bundle cost. Skipped for non-image MIMEs (video, PDF) regardless of this option — those go to the upload pipeline raw.

#### See

[Section titled “See”](#see)

* [CompressOptions](/api/sdk/src/type-aliases/compressoptions/)
* <https://github.com/espaciofuturoio/aquienpz/tree/main/packages/sdk#client-side-compression-browsers>

***

### contentType?

[Section titled “contentType?”](#contenttype)

```ts
optional contentType?: string;
```

Defined in: packages/sdk/src/index.ts:863

MIME type of the bytes. **Only needed for a `Uint8Array` input** — a `File`/`Blob` already carries its `.type`. Raw bytes have no inherent MIME, so without this (and without an extension on `fileName` to infer from) they upload as `application/octet-stream`, which the asset-manager classifies as `kind:"other"` — meaning NO image/video variants are generated and `regenerate()` is unsupported. Resolution order for the effective MIME: `Blob.type` → `contentType` → inferred from `fileName`’s extension → `application/octet-stream`.

aq.upload(bytes, { fileName: “cover.webp” }) // inferred → image/webp ✓ aq.upload(bytes, { contentType: “image/webp” }) // explicit ✓ aq.upload(bytes) // octet-stream → kind:“other” ⚠

***

### fileName?

[Section titled “fileName?”](#filename)

```ts
optional fileName?: string;
```

Defined in: packages/sdk/src/index.ts:849

***

### presets?

[Section titled “presets?”](#presets)

```ts
optional presets?: AssetDTO[];
```

Defined in: packages/sdk/src/index.ts:908

Variant set to generate. **Defaults to `["original"]`** — if you omit this option, only the raw bytes land on the CDN under the `o` path. Pass an explicit array to request more.

Image presets (`thumb` 256 · `sm` 640 · `md` 1280 · `lg` 1920 · `xl` 3840 · `original`):

* `["original"]` (default) → just the raw bytes. Right call for logos / SVGs / anything you’ll resize browser-side or via `aq.assets.regenerate(id, { presets: ["thumb"] })` later.
* `["thumb","sm","md","lg"]` → the classic responsive ladder.
* `["thumb","sm","md","lg","xl"]` → add 4K.

Video presets (`poster`, `video`, `aiproxy`): omit `aiproxy` if the tenant doesn’t need the low-res transcode for AI captioning.

No upscaling. Each size preset is a **ceiling**; a 1080×720 source asked for `xl` (3840) yields a 1080×720 xl variant, not a stretched 3840-wide image.

Idempotent: you can always add missing variants later via `aq.assets.regenerate(id, { presets: [...] })`. The platform stores the source so regeneration doesn’t require re-uploading.

***

### sha256?

[Section titled “sha256?”](#sha256)

```ts
optional sha256?: string;
```

Defined in: packages/sdk/src/index.ts:865

Computed sha256 of bytes. Skip to compute locally with WebCrypto (browser only).

***

### timeoutMs?

[Section titled “timeoutMs?”](#timeoutms)

```ts
optional timeoutMs?: number;
```

Defined in: packages/sdk/src/index.ts:920

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.

Throws `Error("waitReady timeout for <id>")` if the deadline passes without the asset transitioning. The asset row stays in aquienpz (status=“processing”) and the next byHash lookup will return it once processing completes; the caller can resume with their own poll.

***

### video?

[Section titled “video?”](#video)

```ts
optional video?: UploadVideoOptions;
```

Defined in: packages/sdk/src/index.ts:932

VIDEO-only delivery knobs forwarded into `/assets/process`. See [UploadVideoOptions](/api/sdk/src/type-aliases/uploadvideooptions/). Ignored for non-video uploads.

// A delivery-ready reel: skip the unused HLS ladder + skip re-encode. await aq.upload(mp4Bytes, { fileName: “reel.mp4”, presets: \[“poster”, “video”], video: { hls: false, passthrough: true }, });

# UploadResult

```ts
type UploadResult = {
  assetId: string;
  cdnUrl: string;
  sha256: string;
};
```

Defined in: packages/sdk/src/index.ts:938

## Properties

[Section titled “Properties”](#properties)

### assetId

[Section titled “assetId”](#assetid)

```ts
assetId: string;
```

Defined in: packages/sdk/src/index.ts:939

***

### cdnUrl

[Section titled “cdnUrl”](#cdnurl)

```ts
cdnUrl: string;
```

Defined in: packages/sdk/src/index.ts:941

***

### sha256

[Section titled “sha256”](#sha256)

```ts
sha256: string;
```

Defined in: packages/sdk/src/index.ts:940

# UploadUrlResult

```ts
type UploadUrlResult =
  | {
  asset: AssetDTO;
  deduped: true;
}
  | {
  deduped: false;
  process: {
     body: Record<string, unknown>;
     url: string;
  };
  upload: {
     headers?: Record<string, string>;
     url: string;
  };
};
```

Defined in: packages/sdk/src/index.ts:388

Wire shape returned by `POST /assets/upload-url`. Either the server resolves the upload synchronously via dedup (`deduped: true` + existing asset DTO) or it returns a presigned R2 PUT URL plus a `process` payload the caller must POST to `/assets/process` after the PUT lands.

# UploadVideoOptions

```ts
type UploadVideoOptions = {
  hls?: boolean;
  passthrough?: boolean;
};
```

Defined in: packages/sdk/src/index.ts:401

VIDEO-only delivery knobs threaded into `/assets/process`. Ignored for image / audio / other uploads. Both fields default to today’s behavior when omitted, so existing callers are unaffected.

## Properties

[Section titled “Properties”](#properties)

### hls?

[Section titled “hls?”](#hls)

```ts
optional hls?: boolean;
```

Defined in: packages/sdk/src/index.ts:408

`false` → skip the auto-dispatched HLS adaptive ladder (240p–2160p). Use for download-only assets served as a progressive `-v.mp4` and never streamed (e.g. share-video reels) — it avoids a second Cloud Run Job no one watches. Default/absent → the ladder is generated as before.

***

### passthrough?

[Section titled “passthrough?”](#passthrough)

```ts
optional passthrough?: boolean;
```

Defined in: packages/sdk/src/index.ts:417

`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 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 is not web-safe. Default/absent → unconditional re-encode (today’s path).

# UsageDailyPoint

```ts
type UsageDailyPoint = {
  bytesIn: number;
  bytesStored: number;
  date: string;
  deletes: number;
  lists: number;
  processes: number;
  reads: number;
  writes: number;
};
```

Defined in: packages/sdk/src/index.ts:1001

## Properties

[Section titled “Properties”](#properties)

### bytesIn

[Section titled “bytesIn”](#bytesin)

```ts
bytesIn: number;
```

Defined in: packages/sdk/src/index.ts:1008

***

### bytesStored

[Section titled “bytesStored”](#bytesstored)

```ts
bytesStored: number;
```

Defined in: packages/sdk/src/index.ts:1009

***

### date

[Section titled “date”](#date)

```ts
date: string;
```

Defined in: packages/sdk/src/index.ts:1002

***

### deletes

[Section titled “deletes”](#deletes)

```ts
deletes: number;
```

Defined in: packages/sdk/src/index.ts:1006

***

### lists

[Section titled “lists”](#lists)

```ts
lists: number;
```

Defined in: packages/sdk/src/index.ts:1005

***

### processes

[Section titled “processes”](#processes)

```ts
processes: number;
```

Defined in: packages/sdk/src/index.ts:1007

***

### reads

[Section titled “reads”](#reads)

```ts
reads: number;
```

Defined in: packages/sdk/src/index.ts:1003

***

### writes

[Section titled “writes”](#writes)

```ts
writes: number;
```

Defined in: packages/sdk/src/index.ts:1004

# UsagePerKey

```ts
type UsagePerKey = {
  apiKeyId: string;
  bytesTotal: number;
  lastSeen: string;
  name: string | null;
  opsTotal: number;
  prefix: string | null;
};
```

Defined in: packages/sdk/src/index.ts:1012

## Properties

[Section titled “Properties”](#properties)

### apiKeyId

[Section titled “apiKeyId”](#apikeyid)

```ts
apiKeyId: string;
```

Defined in: packages/sdk/src/index.ts:1013

***

### bytesTotal

[Section titled “bytesTotal”](#bytestotal)

```ts
bytesTotal: number;
```

Defined in: packages/sdk/src/index.ts:1017

***

### lastSeen

[Section titled “lastSeen”](#lastseen)

```ts
lastSeen: string;
```

Defined in: packages/sdk/src/index.ts:1018

***

### name

[Section titled “name”](#name)

```ts
name: string | null;
```

Defined in: packages/sdk/src/index.ts:1015

***

### opsTotal

[Section titled “opsTotal”](#opstotal)

```ts
opsTotal: number;
```

Defined in: packages/sdk/src/index.ts:1016

***

### prefix

[Section titled “prefix”](#prefix)

```ts
prefix: string | null;
```

Defined in: packages/sdk/src/index.ts:1014

# UsageSnapshot

```ts
type UsageSnapshot = {
  last30Days: UsageWindow;
  storage: {
     assetCount: number;
     totalBytes: number;
  };
  tenant: {
     code: string;
     id: number;
  };
  today: UsageWindow;
};
```

Defined in: packages/sdk/src/index.ts:983

## Properties

[Section titled “Properties”](#properties)

### last30Days

[Section titled “last30Days”](#last30days)

```ts
last30Days: UsageWindow;
```

Defined in: packages/sdk/src/index.ts:987

***

### storage

[Section titled “storage”](#storage)

```ts
storage: {
  assetCount: number;
  totalBytes: number;
};
```

Defined in: packages/sdk/src/index.ts:985

#### assetCount

[Section titled “assetCount”](#assetcount)

```ts
assetCount: number;
```

#### totalBytes

[Section titled “totalBytes”](#totalbytes)

```ts
totalBytes: number;
```

***

### tenant

[Section titled “tenant”](#tenant)

```ts
tenant: {
  code: string;
  id: number;
};
```

Defined in: packages/sdk/src/index.ts:984

#### code

[Section titled “code”](#code)

```ts
code: string;
```

#### id

[Section titled “id”](#id)

```ts
id: number;
```

***

### today

[Section titled “today”](#today)

```ts
today: UsageWindow;
```

Defined in: packages/sdk/src/index.ts:986

# UsageWindow

```ts
type UsageWindow = {
  admins: number;
  bytesIn: number;
  deletes: number;
  lists: number;
  processes: number;
  reads: number;
  upscales: number;
  writes: number;
};
```

Defined in: packages/sdk/src/index.ts:990

## Properties

[Section titled “Properties”](#properties)

### admins

[Section titled “admins”](#admins)

```ts
admins: number;
```

Defined in: packages/sdk/src/index.ts:995

***

### bytesIn

[Section titled “bytesIn”](#bytesin)

```ts
bytesIn: number;
```

Defined in: packages/sdk/src/index.ts:998

***

### deletes

[Section titled “deletes”](#deletes)

```ts
deletes: number;
```

Defined in: packages/sdk/src/index.ts:994

***

### lists

[Section titled “lists”](#lists)

```ts
lists: number;
```

Defined in: packages/sdk/src/index.ts:993

***

### processes

[Section titled “processes”](#processes)

```ts
processes: number;
```

Defined in: packages/sdk/src/index.ts:997

***

### reads

[Section titled “reads”](#reads)

```ts
reads: number;
```

Defined in: packages/sdk/src/index.ts:991

***

### upscales

[Section titled “upscales”](#upscales)

```ts
upscales: number;
```

Defined in: packages/sdk/src/index.ts:996

***

### writes

[Section titled “writes”](#writes)

```ts
writes: number;
```

Defined in: packages/sdk/src/index.ts:992

# AssetsApi

Defined in: packages/sdk/src/index.ts:478

## Constructors

[Section titled “Constructors”](#constructors)

### Constructor

[Section titled “Constructor”](#constructor)

```ts
new AssetsApi(opts): AssetsApi;
```

Defined in: packages/sdk/src/index.ts:479

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                        |
| --------- | --------------------------------------------------------------------------- |
| `opts`    | [`AquienpzClientOptions`](/api/sdk/src/type-aliases/aquienpzclientoptions/) |

#### Returns

[Section titled “Returns”](#returns)

`AssetsApi`

## Methods

[Section titled “Methods”](#methods)

### bindings()

[Section titled “bindings()”](#bindings)

```ts
bindings(assetId): Promise<{
  description: string | null;
  preset: any;
  slotKey: string;
  updatedAt: string;
  updatedBy: string | null;
}[]>;
```

Defined in: packages/sdk/src/index.ts:540

Slot bindings pointing at an asset. Use this before deleting an asset so the admin sees which storefront slots would suddenly resolve to nothing.

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter | Type     |
| --------- | -------- |
| `assetId` | `string` |

#### Returns

[Section titled “Returns”](#returns-1)

`Promise`<{ `description`: `string` | `null`; `preset`: `any`; `slotKey`: `string`; `updatedAt`: `string`; `updatedBy`: `string` | `null`; }\[]>

***

### byHash()

[Section titled “byHash()”](#byhash)

```ts
byHash(sha256): Promise<any>;
```

Defined in: packages/sdk/src/index.ts:482

Look up an asset by full sha256 (64 hex). Returns null on 404.

#### Parameters

[Section titled “Parameters”](#parameters-2)

| Parameter | Type     |
| --------- | -------- |
| `sha256`  | `string` |

#### Returns

[Section titled “Returns”](#returns-2)

`Promise`<`any`>

***

### byHashes()

[Section titled “byHashes()”](#byhashes)

```ts
byHashes(hashes): Promise<{
  existing: AssetDTO[];
  missing: string[];
}>;
```

Defined in: packages/sdk/src/index.ts:493

Bulk lookup by sha256s.

#### Parameters

[Section titled “Parameters”](#parameters-3)

| Parameter | Type        |
| --------- | ----------- |
| `hashes`  | `string`\[] |

#### Returns

[Section titled “Returns”](#returns-3)

`Promise`<{ `existing`: `AssetDTO`\[]; `missing`: `string`\[]; }>

***

### composeMarketing()

[Section titled “composeMarketing()”](#composemarketing)

```ts
composeMarketing(opts): Promise<ComposeMarketingResult>;
```

Defined in: packages/sdk/src/index.ts:754

Dispatch `POST /assets/compose-marketing` to stitch pre-uploaded clip segments into a single MP4 composition. Returns the processing asset id immediately — does NOT block on completion. Callers poll via [waitReady](/api/sdk/src/web/-internal-/classes/assetsapi/#waitready) (typical timeout: 10 min for multi-segment kits).

Tenant scope is inherited from the SDK client; `tenantCode` is added to the request body so the Cloud Run Job can resolve it without re-reading the header.

#### Parameters

[Section titled “Parameters”](#parameters-4)

| Parameter | Type                                                                            |
| --------- | ------------------------------------------------------------------------------- |
| `opts`    | [`ComposeMarketingOptions`](/api/sdk/src/type-aliases/composemarketingoptions/) |

#### Returns

[Section titled “Returns”](#returns-4)

`Promise`<[`ComposeMarketingResult`](/api/sdk/src/type-aliases/composemarketingresult/)>

***

### get()

[Section titled “get()”](#get)

```ts
get(assetId): Promise<any>;
```

Defined in: packages/sdk/src/index.ts:527

Full DTO for an asset (admin view — includes audit-only fields).

#### Parameters

[Section titled “Parameters”](#parameters-5)

| Parameter | Type     |
| --------- | -------- |
| `assetId` | `string` |

#### Returns

[Section titled “Returns”](#returns-5)

`Promise`<`any`>

***

### list()

[Section titled “list()”](#list)

```ts
list(opts?): Promise<{
  assets: AssetDTO[];
  nextCursor: string | null;
}>;
```

Defined in: packages/sdk/src/index.ts:507

Paginated list of recent assets for the tenant.

#### Parameters

[Section titled “Parameters”](#parameters-6)

| Parameter              | Type                                                                       |
| ---------------------- | -------------------------------------------------------------------------- |
| `opts`                 | { `cursor?`: `string`; `includeDeleted?`: `boolean`; `limit?`: `number`; } |
| `opts.cursor?`         | `string`                                                                   |
| `opts.includeDeleted?` | `boolean`                                                                  |
| `opts.limit?`          | `number`                                                                   |

#### Returns

[Section titled “Returns”](#returns-6)

`Promise`<{ `assets`: `AssetDTO`\[]; `nextCursor`: `string` | `null`; }>

***

### patchMetadata()

[Section titled “patchMetadata()”](#patchmetadata)

```ts
patchMetadata(assetId, metadata): Promise<{
  metadata: Record<string, unknown>;
  ok: true;
}>;
```

Defined in: packages/sdk/src/index.ts:624

Merge metadata into an asset (role / slot / description / tags).

#### Parameters

[Section titled “Parameters”](#parameters-7)

| Parameter  | Type                                                                              |
| ---------- | --------------------------------------------------------------------------------- |
| `assetId`  | `string`                                                                          |
| `metadata` | [`Record`](/api/sdk/src/web/-internal-/type-aliases/record/)<`string`, `unknown`> |

#### Returns

[Section titled “Returns”](#returns-7)

`Promise`<{ `metadata`: [`Record`](/api/sdk/src/web/-internal-/type-aliases/record/)<`string`, `unknown`>; `ok`: `true`; }>

***

### presignUploadUrl()

[Section titled “presignUploadUrl()”](#presignuploadurl)

```ts
presignUploadUrl(opts): Promise<UploadUrlResult>;
```

Defined in: packages/sdk/src/index.ts:669

Request a presigned R2 PUT URL for direct browser-side uploads.

Mirrors the first half of `aq.upload()` — the caller (typically a BFF / share-link dropzone) computes sha256 in the browser, then uploads bytes straight to R2 with the returned `upload.url`, then POSTs `process.body` to `/assets/process` (see [processAndWait](/api/sdk/src/web/-internal-/classes/assetsapi/#processandwait)) once R2 has the bytes.

If the sha is already known to the tenant the server short-circuits with `{ deduped: true, asset }` — no PUT needed.

#### Parameters

[Section titled “Parameters”](#parameters-8)

| Parameter | Type                                                                            |
| --------- | ------------------------------------------------------------------------------- |
| `opts`    | [`PresignUploadUrlOptions`](/api/sdk/src/type-aliases/presignuploadurloptions/) |

#### Returns

[Section titled “Returns”](#returns-8)

`Promise`<[`UploadUrlResult`](/api/sdk/src/type-aliases/uploadurlresult/)>

#### Example

[Section titled “Example”](#example)

**The browser-direct flow, in full**

```ts
// SERVER (holds the amk_rt_* key — never the browser):
const presign = await aq.assets.presignUploadUrl({ sha256, mime, bytes, fileName, presets });
if (presign.deduped) return presign.asset;      // those bytes already exist; none fly


// BROWSER: PUT straight to presign.upload.url — the bytes never touch your server.
// ⚠️ R2 answers that preflight ITSELF, so your origin must be in the BUCKET's CORS policy.
//    Symptom when it is not: "PUT failed: network error" with every earlier step green —
//    and it cannot be fixed in this SDK, in your app, or in `storefront_origins`.


// SERVER again, forwarding presign.process.body VERBATIM:
const asset = await aq.assets.processAndWait(presign.process.body, { timeoutMs: 300_000 });
```

Works for images AND video. A video answers immediately with `{ assetId, status: "processing" }` while a Cloud Run Job transcodes, so give `processAndWait` a bigger `timeoutMs` (a transcode + HLS ladder runs 1–2 min; 300\_000 is a sane floor).

***

### processAndWait()

[Section titled “processAndWait()”](#processandwait)

```ts
processAndWait(processBody, opts?): Promise<AssetDTO>;
```

Defined in: packages/sdk/src/index.ts:701

Dispatch `/assets/process` with the body returned by a prior [presignUploadUrl](/api/sdk/src/web/-internal-/classes/assetsapi/#presignuploadurl) call, then poll until the asset transitions to `ready` or `failed`. Throws on `failed` or timeout.

Use this when bytes were uploaded directly from the browser to R2 — `aq.upload()` already does presign + PUT + process + wait in one step when the server holds the bytes.

#### Parameters

[Section titled “Parameters”](#parameters-9)

| Parameter         | Type                                                                              |
| ----------------- | --------------------------------------------------------------------------------- |
| `processBody`     | [`Record`](/api/sdk/src/web/-internal-/type-aliases/record/)<`string`, `unknown`> |
| `opts`            | { `timeoutMs?`: `number`; }                                                       |
| `opts.timeoutMs?` | `number`                                                                          |

#### Returns

[Section titled “Returns”](#returns-9)

`Promise`<`AssetDTO`>

***

### regenerate()

[Section titled “regenerate()”](#regenerate)

```ts
regenerate(assetId, opts?): Promise<RegenerateResult>;
```

Defined in: packages/sdk/src/index.ts:606

Add or rebuild variants on an existing asset. Image presets are MERGED with what’s there — passing `{ presets: ["thumb"] }` adds the thumb variant without touching `lg`, `sm`, `original`, etc.

// Day 0: upload original-only logo const { assetId } = await aq.upload(logoFile); // defaults to \[“original”]

// Day 7: need a thumb without re-uploading await aq.assets.regenerate(assetId, { presets: \[“thumb”] });

const after = await aq.assets.variants(assetId); after.map((v) => v.preset); // → \[“original”, “thumb”]

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.

Video presets are filtered to `["poster","video","aiproxy"]` and dispatched to the Cloud Run Job (the call returns immediately with a dispatch handle; poll `aq.assets.get(id).status` for completion).

#### Parameters

[Section titled “Parameters”](#parameters-10)

| Parameter       | Type                                |
| --------------- | ----------------------------------- |
| `assetId`       | `string`                            |
| `opts`          | { `presets?`: `VariantPreset`\[]; } |
| `opts.presets?` | `VariantPreset`\[]                  |

#### Returns

[Section titled “Returns”](#returns-10)

`Promise`<[`RegenerateResult`](/api/sdk/src/type-aliases/regenerateresult/)>

***

### variants()

[Section titled “variants()”](#variants)

```ts
variants(assetId): Promise<AssetVariant[]>;
```

Defined in: packages/sdk/src/index.ts:573

Full variant list for an asset — preset, URL, dimensions, bytes. Stronger-typed wrapper around `get()` that exposes only the `variants` field with the proper `AssetVariant[]` shape.

const v = await aq.assets.variants(logoId); v.map((x) => x.preset); // → (“thumb” | “sm” | … | “original”)\[]

#### Parameters

[Section titled “Parameters”](#parameters-11)

| Parameter | Type     |
| --------- | -------- |
| `assetId` | `string` |

#### Returns

[Section titled “Returns”](#returns-11)

`Promise`<`AssetVariant`\[]>

***

### waitReady()

[Section titled “waitReady()”](#waitready)

```ts
waitReady(assetId, timeoutMs?): Promise<AssetDTO>;
```

Defined in: packages/sdk/src/index.ts:730

Poll `GET /assets/:id` until the asset transitions to `ready` or `failed`. Returns the final DTO (whether ready OR failed — callers decide whether to throw on `failed`). Throws on timeout.

Default timeout is 5 minutes; videos / HLS ladders may need a higher cap (pass `10 * 60_000` for compositions, transcodes).

#### Parameters

[Section titled “Parameters”](#parameters-12)

| Parameter   | Type     |
| ----------- | -------- |
| `assetId`   | `string` |
| `timeoutMs` | `number` |

#### Returns

[Section titled “Returns”](#returns-12)

`Promise`<`AssetDTO`>

# SlotsApi

Defined in: packages/sdk/src/index.ts:228

## Constructors

[Section titled “Constructors”](#constructors)

### Constructor

[Section titled “Constructor”](#constructor)

```ts
new SlotsApi(opts): SlotsApi;
```

Defined in: packages/sdk/src/index.ts:229

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                        |
| --------- | --------------------------------------------------------------------------- |
| `opts`    | [`AquienpzClientOptions`](/api/sdk/src/type-aliases/aquienpzclientoptions/) |

#### Returns

[Section titled “Returns”](#returns)

`SlotsApi`

## Methods

[Section titled “Methods”](#methods)

### bind()

[Section titled “bind()”](#bind)

```ts
bind(slotKey, body): Promise<{
  assetId: string;
  ok: true;
  slotKey: string;
}>;
```

Defined in: packages/sdk/src/index.ts:262

Bind / rebind a slot to an asset. Admin-only operation.

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter           | Type                                                                                         |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `slotKey`           | `string`                                                                                     |
| `body`              | { `assetId`: `string`; `description?`: `string`; `preset?`: `any`; `updatedBy?`: `string`; } |
| `body.assetId`      | `string`                                                                                     |
| `body.description?` | `string`                                                                                     |
| `body.preset?`      | `any`                                                                                        |
| `body.updatedBy?`   | `string`                                                                                     |

#### Returns

[Section titled “Returns”](#returns-1)

`Promise`<{ `assetId`: `string`; `ok`: `true`; `slotKey`: `string`; }>

***

### history()

[Section titled “history()”](#history)

```ts
history(slotKey, opts?): Promise<SlotHistoryEntry[]>;
```

Defined in: packages/sdk/src/index.ts:288

Recent bindings for a slot. Lets the admin audit who changed what and restore a previous binding without remembering the asset id. Default limit 20, max 100.

#### Parameters

[Section titled “Parameters”](#parameters-2)

| Parameter     | Type                    |
| ------------- | ----------------------- |
| `slotKey`     | `string`                |
| `opts`        | { `limit?`: `number`; } |
| `opts.limit?` | `number`                |

#### Returns

[Section titled “Returns”](#returns-2)

`Promise`<[`SlotHistoryEntry`](/api/sdk/src/type-aliases/slothistoryentry/)\[]>

***

### invalidateCache()

[Section titled “invalidateCache()”](#invalidatecache)

```ts
invalidateCache(slotKey?): void;
```

Defined in: packages/sdk/src/index.ts:338

Invalidate the in-process cache after a slot rebind.

#### Parameters

[Section titled “Parameters”](#parameters-3)

| Parameter  | Type     |
| ---------- | -------- |
| `slotKey?` | `string` |

#### Returns

[Section titled “Returns”](#returns-3)

`void`

***

### list()

[Section titled “list()”](#list)

```ts
list(opts?): Promise<SlotDTO[]>;
```

Defined in: packages/sdk/src/index.ts:248

List slots for the tenant (admin). Optional prefix filter for tree views.

#### Parameters

[Section titled “Parameters”](#parameters-4)

| Parameter      | Type                                         |
| -------------- | -------------------------------------------- |
| `opts`         | { `limit?`: `number`; `prefix?`: `string`; } |
| `opts.limit?`  | `number`                                     |
| `opts.prefix?` | `string`                                     |

#### Returns

[Section titled “Returns”](#returns-4)

`Promise`<`SlotDTO`\[]>

***

### resolve()

[Section titled “resolve()”](#resolve)

```ts
resolve(slotKey, options?): Promise<SlotResolution>;
```

Defined in: packages/sdk/src/index.ts:232

Resolve one slot — returns `{slot, preset, url}` or `{slot: null, url: null}` when unbound.

#### Parameters

[Section titled “Parameters”](#parameters-5)

| Parameter | Type                 |
| --------- | -------------------- |
| `slotKey` | `string`             |
| `options` | `ResolveSlotOptions` |

#### Returns

[Section titled “Returns”](#returns-5)

`Promise`<`SlotResolution`>

***

### resolveMany()

[Section titled “resolveMany()”](#resolvemany)

```ts
resolveMany(slotKeys, options?): Promise<Record<string, SlotResolution>>;
```

Defined in: packages/sdk/src/index.ts:240

Bulk-resolve N slots in one HTTP round-trip.

#### Parameters

[Section titled “Parameters”](#parameters-6)

| Parameter  | Type                 |
| ---------- | -------------------- |
| `slotKeys` | `string`\[]          |
| `options`  | `ResolveSlotOptions` |

#### Returns

[Section titled “Returns”](#returns-6)

`Promise`<[`Record`](/api/sdk/src/web/-internal-/type-aliases/record/)<`string`, `SlotResolution`>>

***

### restore()

[Section titled “restore()”](#restore)

```ts
restore(slotKey, args): Promise<{
  assetId: string;
  ok: true;
  slotKey: string;
}>;
```

Defined in: packages/sdk/src/index.ts:308

Restore the slot to a previous binding. Equivalent to `bind(key, { assetId: previous.assetId, action: "restore" })` — the audit row is tagged `restore` instead of `bind`.

#### Parameters

[Section titled “Parameters”](#parameters-7)

| Parameter         | Type                                                               |
| ----------------- | ------------------------------------------------------------------ |
| `slotKey`         | `string`                                                           |
| `args`            | { `assetId`: `string`; `preset?`: `any`; `updatedBy?`: `string`; } |
| `args.assetId`    | `string`                                                           |
| `args.preset?`    | `any`                                                              |
| `args.updatedBy?` | `string`                                                           |

#### Returns

[Section titled “Returns”](#returns-7)

`Promise`<{ `assetId`: `string`; `ok`: `true`; `slotKey`: `string`; }>

***

### unbind()

[Section titled “unbind()”](#unbind)

```ts
unbind(slotKey): Promise<{
  ok: true;
  removed: number;
}>;
```

Defined in: packages/sdk/src/index.ts:325

Remove a slot binding. The asset itself is left alone.

#### Parameters

[Section titled “Parameters”](#parameters-8)

| Parameter | Type     |
| --------- | -------- |
| `slotKey` | `string` |

#### Returns

[Section titled “Returns”](#returns-8)

`Promise`<{ `ok`: `true`; `removed`: `number`; }>

# UsageApi

Defined in: packages/sdk/src/index.ts:1021

## Constructors

[Section titled “Constructors”](#constructors)

### Constructor

[Section titled “Constructor”](#constructor)

```ts
new UsageApi(opts): UsageApi;
```

Defined in: packages/sdk/src/index.ts:1022

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                        |
| --------- | --------------------------------------------------------------------------- |
| `opts`    | [`AquienpzClientOptions`](/api/sdk/src/type-aliases/aquienpzclientoptions/) |

#### Returns

[Section titled “Returns”](#returns)

`UsageApi`

## Methods

[Section titled “Methods”](#methods)

### keys()

[Section titled “keys()”](#keys)

```ts
keys(): Promise<{
  keys: UsagePerKey[];
  monthStart: string;
  tenant: {
     code: string;
     id: number;
  };
}>;
```

Defined in: packages/sdk/src/index.ts:1051

Per-API-key breakdown for the current month.

#### Returns

[Section titled “Returns”](#returns-1)

`Promise`<{ `keys`: [`UsagePerKey`](/api/sdk/src/type-aliases/usageperkey/)\[]; `monthStart`: `string`; `tenant`: { `code`: `string`; `id`: `number`; }; }>

***

### snapshot()

[Section titled “snapshot()”](#snapshot)

```ts
snapshot(): Promise<UsageSnapshot>;
```

Defined in: packages/sdk/src/index.ts:1025

Snapshot for the active tenant — storage + today + last 30 days totals.

#### Returns

[Section titled “Returns”](#returns-2)

`Promise`<[`UsageSnapshot`](/api/sdk/src/type-aliases/usagesnapshot/)>

***

### timeseries()

[Section titled “timeseries()”](#timeseries)

```ts
timeseries(days?): Promise<{
  days: UsageDailyPoint[];
  tenant: {
     code: string;
     id: number;
  };
}>;
```

Defined in: packages/sdk/src/index.ts:1034

Daily rollup for charts — 1..365 days, default 30.

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter | Type     | Default value |
| --------- | -------- | ------------- |
| `days`    | `number` | `30`          |

#### Returns

[Section titled “Returns”](#returns-3)

`Promise`<{ `days`: [`UsageDailyPoint`](/api/sdk/src/type-aliases/usagedailypoint/)\[]; `tenant`: { `code`: `string`; `id`: `number`; }; }>

# ArrayBufferLike

```ts
type ArrayBufferLike = ArrayBufferTypes[keyof ArrayBufferTypes];
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1718

# Record

```ts
type Record<K, T> = { [P in K]: T };
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1611

Construct a type with a set of properties K of type T

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter            |
| ------------------------- |
| `K` *extends* keyof `any` |
| `T`                       |

# Required

```ts
type Required<T> = { [P in keyof T]-?: T[P] };
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1590

Make all properties in T required

## Type Parameters

[Section titled “Type Parameters”](#type-parameters)

| Type Parameter |
| -------------- |
| `T`            |

# AquienpzClient

Defined in: packages/sdk/src/web/index.ts:87

Browser-safe `AquienpzClient` — same runtime as the root class, but the constructor’s type rejects `apiKey` / `signingKey`. Calls go through your BFF (typically a same-origin route like `/api/am/...`).

For server-side instantiation (Node/Bun/edge), import from `@aquienpz/sdk/server` instead.

## Extends

[Section titled “Extends”](#extends)

* [`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/)

## Constructors

[Section titled “Constructors”](#constructors)

### Constructor

[Section titled “Constructor”](#constructor)

```ts
new AquienpzClient(opts): AquienpzClient;
```

Defined in: packages/sdk/src/web/index.ts:88

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                  |
| --------- | --------------------------------------------------------------------- |
| `opts`    | [`WebClientOptions`](/api/sdk/src/web/type-aliases/webclientoptions/) |

#### Returns

[Section titled “Returns”](#returns)

`AquienpzClient`

#### Overrides

[Section titled “Overrides”](#overrides)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`constructor`](/api/sdk/src/classes/aquienpzclient/#constructor)

## Properties

[Section titled “Properties”](#properties)

### assets

[Section titled “assets”](#assets)

```ts
readonly assets: AssetsApi;
```

Defined in: packages/sdk/src/index.ts:1074

#### Inherited from

[Section titled “Inherited from”](#inherited-from)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`assets`](/api/sdk/src/classes/aquienpzclient/#assets)

***

### opts

[Section titled “opts”](#opts)

```ts
readonly opts: AquienpzClientOptions;
```

Defined in: packages/sdk/src/index.ts:1081

Effective options — read-only. Exposed so the `/web` and `/expo` subpaths can inherit endpoint / apiKey / tenant scope from the configured client without re-passing them per call site.

#### Inherited from

[Section titled “Inherited from”](#inherited-from-1)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`opts`](/api/sdk/src/classes/aquienpzclient/#opts)

***

### slots

[Section titled “slots”](#slots)

```ts
readonly slots: SlotsApi;
```

Defined in: packages/sdk/src/index.ts:1073

#### Inherited from

[Section titled “Inherited from”](#inherited-from-2)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`slots`](/api/sdk/src/classes/aquienpzclient/#slots)

***

### usage

[Section titled “usage”](#usage)

```ts
readonly usage: UsageApi;
```

Defined in: packages/sdk/src/index.ts:1075

#### Inherited from

[Section titled “Inherited from”](#inherited-from-3)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`usage`](/api/sdk/src/classes/aquienpzclient/#usage)

## Accessors

[Section titled “Accessors”](#accessors)

### tenantSegment

[Section titled “tenantSegment”](#tenantsegment)

#### Get Signature

[Section titled “Get Signature”](#get-signature)

```ts
get tenantSegment(): string;
```

Defined in: packages/sdk/src/index.ts:1102

Tenant id as base36 path segment (e.g. tenantId=4 → “4/v/”).

##### Returns

[Section titled “Returns”](#returns-1)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-4)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`tenantSegment`](/api/sdk/src/classes/aquienpzclient/#tenantsegment)

## Methods

[Section titled “Methods”](#methods)

### srcSetFor()

[Section titled “srcSetFor()”](#srcsetfor)

```ts
srcSetFor(asset): string;
```

Defined in: packages/sdk/src/index.ts:1112

Build a responsive srcSet across the available image presets.

#### Parameters

[Section titled “Parameters”](#parameters-1)

| Parameter | Type                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"` \| `"presets"`> |

#### Returns

[Section titled “Returns”](#returns-2)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-5)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`srcSetFor`](/api/sdk/src/classes/aquienpzclient/#srcsetfor)

***

### streamingUrl()

[Section titled “streamingUrl()”](#streamingurl)

```ts
streamingUrl(asset, opts?): string;
```

Defined in: packages/sdk/src/index.ts:1287

Build the HLS master playlist URL for a VIDEO asset (Phase 5).

Returns `<cdn>/t/format=hls(,start=…,duration=…)/<sha>.m3u8`. Pass to an HLS-aware player:

\<video src={aq.streamingUrl(asset)} controls playsInline // Video.js v10’s @videojs/http-streaming ships native HLS — // no plugin needed. />

On the first request the server returns **202 Accepted** while a Cloud Run Job builds the multi-rung ladder (typically 1-3 min for a 90 s source — five rungs of 240p/360p/480p/720p/1080p @ AAC). Subsequent requests hit the cache → **302** to the master.m3u8.

Supports `start` + `duration` to ladder a sub-clip. Other DSL params (width, height, fit) are ignored on the HLS path because the rungs determine resolution.

#### Parameters

[Section titled “Parameters”](#parameters-2)

| Parameter | Type                                                                                                                         |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`>       |
| `opts`    | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"format"`> |

#### Returns

[Section titled “Returns”](#returns-3)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-6)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`streamingUrl`](/api/sdk/src/classes/aquienpzclient/#streamingurl)

***

### transform()

[Section titled “transform()”](#transform)

#### Call Signature

[Section titled “Call Signature”](#call-signature)

```ts
transform(asset, opts?): string;
```

Defined in: packages/sdk/src/index.ts:1145

Build an on-the-fly transform URL — `<cdn>/t/<dsl>/<sha>.<ext>`.

## URL CONVENTION — transforms are NOT tenant-prefixed (variants are)

[Section titled “URL CONVENTION — transforms are NOT tenant-prefixed (variants are)”](#url-convention--transforms-are-not-tenant-prefixed-variants-are)

Two distinct delivery paths, by design:

* **Variants / presets** (`urlFor`, `srcSetFor`, upload `cdnUrl`): `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>` ← tenant-scoped (e.g. `/4/v/<sha>-lg.webp`)
* **On-the-fly transforms** (`transform`, `transformSrcSet`): `<cdn>/t/<dsl>/<sha>.<ext>` ← GLOBAL, no tenant segment (`/t/...`) The transform service is content-addressed by sha + resizes from the source on demand, so it needs no tenant in the path. Prefixing a transform URL with `/<tenant>/t/...` 404s. Consumers that build URLs by hand must NOT add the tenant segment to `/t/` URLs.

Returns the canonical `lg` variant URL when called with empty options, so callers can swap `urlFor()` for `transform()` without thinking.

URLs with the same params in different order produce the same R2 cache entry (the server canonicalizes both sides). Safe to use as stable cache keys.

\<Image src={aq.transform(asset, { width: 1280 })} srcSet={aq.transformSrcSet(asset, \[640, 960, 1280, 1920])} sizes=“(max-width: 768px) 100vw, 50vw” />

##### Parameters

[Section titled “Parameters”](#parameters-3)

| Parameter | Type                                                                                                                   |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `opts?`   | `any`                                                                                                                  |

##### Returns

[Section titled “Returns”](#returns-4)

`string`

##### See

[Section titled “See”](#see)

[TransformOptions](/api/sdk/src/type-aliases/assetdto/) for the full param matrix.

##### Inherited from

[Section titled “Inherited from”](#inherited-from-7)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transform`](/api/sdk/src/classes/aquienpzclient/#transform)

#### Call Signature

[Section titled “Call Signature”](#call-signature-1)

```ts
transform(
   asset,
   opts,
signOpts): Promise<string>;
```

Defined in: packages/sdk/src/index.ts:1149

Build an on-the-fly transform URL — `<cdn>/t/<dsl>/<sha>.<ext>`.

## URL CONVENTION — transforms are NOT tenant-prefixed (variants are)

[Section titled “URL CONVENTION — transforms are NOT tenant-prefixed (variants are)”](#url-convention--transforms-are-not-tenant-prefixed-variants-are-1)

Two distinct delivery paths, by design:

* **Variants / presets** (`urlFor`, `srcSetFor`, upload `cdnUrl`): `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>` ← tenant-scoped (e.g. `/4/v/<sha>-lg.webp`)
* **On-the-fly transforms** (`transform`, `transformSrcSet`): `<cdn>/t/<dsl>/<sha>.<ext>` ← GLOBAL, no tenant segment (`/t/...`) The transform service is content-addressed by sha + resizes from the source on demand, so it needs no tenant in the path. Prefixing a transform URL with `/<tenant>/t/...` 404s. Consumers that build URLs by hand must NOT add the tenant segment to `/t/` URLs.

Returns the canonical `lg` variant URL when called with empty options, so callers can swap `urlFor()` for `transform()` without thinking.

URLs with the same params in different order produce the same R2 cache entry (the server canonicalizes both sides). Safe to use as stable cache keys.

\<Image src={aq.transform(asset, { width: 1280 })} srcSet={aq.transformSrcSet(asset, \[640, 960, 1280, 1920])} sizes=“(max-width: 768px) 100vw, 50vw” />

##### Parameters

[Section titled “Parameters”](#parameters-4)

| Parameter       | Type                                                                                                                   |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`         | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `opts`          | `SignedTransformOptions`                                                                                               |
| `signOpts`      | { `sign`: `true`; }                                                                                                    |
| `signOpts.sign` | `true`                                                                                                                 |

##### Returns

[Section titled “Returns”](#returns-5)

`Promise`<`string`>

##### See

[Section titled “See”](#see-1)

[TransformOptions](/api/sdk/src/type-aliases/assetdto/) for the full param matrix.

##### Inherited from

[Section titled “Inherited from”](#inherited-from-8)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transform`](/api/sdk/src/classes/aquienpzclient/#transform)

***

### transformSrcSet()

[Section titled “transformSrcSet()”](#transformsrcset)

#### Call Signature

[Section titled “Call Signature”](#call-signature-2)

```ts
transformSrcSet(
   asset,
   widths,
   extraOpts?): string;
```

Defined in: packages/sdk/src/index.ts:1189

Build a responsive `srcSet` string. One transform URL per width; all other options apply to every URL.

Pass `{ sign: true }` to return signed URLs (async). Without it, the call stays synchronous as before.

##### Parameters

[Section titled “Parameters”](#parameters-5)

| Parameter    | Type                                                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`      | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `widths`     | `number`\[]                                                                                                            |
| `extraOpts?` | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<`TransformOptions`, `"width"`>                           |

##### Returns

[Section titled “Returns”](#returns-6)

`string`

##### Inherited from

[Section titled “Inherited from”](#inherited-from-9)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transformSrcSet`](/api/sdk/src/classes/aquienpzclient/#transformsrcset)

#### Call Signature

[Section titled “Call Signature”](#call-signature-3)

```ts
transformSrcSet(
   asset,
   widths,
   extraOpts,
signOpts): Promise<string>;
```

Defined in: packages/sdk/src/index.ts:1194

Build a responsive `srcSet` string. One transform URL per width; all other options apply to every URL.

Pass `{ sign: true }` to return signed URLs (async). Without it, the call stays synchronous as before.

##### Parameters

[Section titled “Parameters”](#parameters-6)

| Parameter       | Type                                                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `asset`         | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`>      |
| `widths`        | `number`\[]                                                                                                                 |
| `extraOpts`     | [`Omit`](/api/asset-client/src/-internal-/type-aliases/omit/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"width"`> |
| `signOpts`      | { `sign`: `true`; }                                                                                                         |
| `signOpts.sign` | `true`                                                                                                                      |

##### Returns

[Section titled “Returns”](#returns-7)

`Promise`<`string`>

##### Inherited from

[Section titled “Inherited from”](#inherited-from-10)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transformSrcSet`](/api/sdk/src/classes/aquienpzclient/#transformsrcset)

***

### transformVideo()

[Section titled “transformVideo()”](#transformvideo)

```ts
transformVideo(asset, opts?): string;
```

Defined in: packages/sdk/src/index.ts:1258

Build an on-the-fly VIDEO transform URL — Phase 4.

Same DSL shape as `transform()` but the URL has a `.mp4` (default) or `.webm` extension and the server routes the request to a Cloud Run Job for ffmpeg encoding (vs the inline sharp pipeline for images).

On the first request the route returns **202 Accepted** with `Retry-After: 10` while the Job 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.

const url = aq.transformVideo(asset, { width: 1080, height: 1920, fit: “cover”, start: 0, duration: 15, }); // Pass to Video.js / [; on the first load it // gets 202 + body.outputUrl; subsequent loads hit cache → 302.]({url})

Video-specific DSL params:

* `start` (seconds, decimal OK)
* `duration` (seconds, 1..300)
* `format`: “mp4” (default) or “webm”

The other params (`width`, `height`, `fit`) work identically to image transforms. `gravity`, `quality`, `effect`, `dpr` are accepted by the DSL but currently ignored on the video path.

#### Parameters

[Section titled “Parameters”](#parameters-7)

| Parameter | Type                                                                                                                   |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> |
| `opts`    | `TransformOptions`                                                                                                     |

#### Returns

[Section titled “Returns”](#returns-8)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-11)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`transformVideo`](/api/sdk/src/classes/aquienpzclient/#transformvideo)

***

### upload()

[Section titled “upload()”](#upload)

```ts
upload(input, opts?): Promise<UploadResult>;
```

Defined in: packages/sdk/src/index.ts:1348

Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-R2 PUT** → `/assets/process` → wait until the asset is ready.

⚠️ `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”.

#### Parameters

[Section titled “Parameters”](#parameters-8)

| Parameter | Type                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------- |
| `input`   | \| `File` \| `Blob` \| `Uint8Array`<[`ArrayBufferLike`](/api/sdk/src/web/-internal-/type-aliases/arraybufferlike/)> |
| `opts`    | [`UploadOptions`](/api/sdk/src/type-aliases/uploadoptions/)                                                         |

#### Returns

[Section titled “Returns”](#returns-9)

`Promise`<[`UploadResult`](/api/sdk/src/type-aliases/uploadresult/)>

#### Examples

[Section titled “Examples”](#examples)

**Deliver an image on a site (the responsive ladder)**

```ts
import { AquienpzClient } from "@aquienpz/sdk/server";


const aq = new AquienpzClient({ endpoint, apiKey, tenantCode, tenantId });
const { assetId, sha256 } = await aq.upload(file, {
  fileName: file.name,
  presets: ["thumb", "sm", "md", "lg"],
});
```

**ARCHIVE a file — you must ask for \`original\`**

```ts
await aq.upload(bytes, {
  fileName: "contrato.pdf",
  contentType: "application/pdf",
  presets: ["original"],          // without this the bytes are unrecoverable
});
```

**Raw bytes need an explicit MIME**

```ts
await aq.upload(bytes, { fileName: "track.mp3", contentType: "audio/mpeg" });
// Without either, it stores as kind:"other" — no variants, and regenerate() is unsupported.
```

**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.
await aq.upload(clip, { fileName: "tour.mp4", presets: ["poster", "video"] });


// Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost Job time
// and permanent R2 objects that nothing else reads.
```

#### Inherited from

[Section titled “Inherited from”](#inherited-from-12)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`upload`](/api/sdk/src/classes/aquienpzclient/#upload)

***

### urlFor()

[Section titled “urlFor()”](#urlfor)

```ts
urlFor(asset, preset?): string;
```

Defined in: packages/sdk/src/index.ts:1107

Build the canonical CDN URL deterministically from sha + preset.

#### Parameters

[Section titled “Parameters”](#parameters-9)

| Parameter | Type                                                                                                                   | Default value |
| --------- | ---------------------------------------------------------------------------------------------------------------------- | ------------- |
| `asset`   | [`Pick`](/api/sdk/src/react/-internal-/type-aliases/pick/)<[`AssetDTO`](/api/sdk/src/type-aliases/assetdto/), `"sha"`> | `undefined`   |
| `preset`  | `VariantPreset`                                                                                                        | `"lg"`        |

#### Returns

[Section titled “Returns”](#returns-10)

`string`

#### Inherited from

[Section titled “Inherited from”](#inherited-from-13)

[`AquienpzClient`](/api/sdk/src/classes/aquienpzclient/).[`urlFor`](/api/sdk/src/classes/aquienpzclient/#urlfor)

# compressImage

```ts
function compressImage(file, opts?): Promise<CompressResult>;
```

Defined in: packages/sdk/src/web/index.ts:249

Compress a single image. Browser-only; in Node/Bun this is a no-op that returns the input unchanged (with a warning).

Dynamically imports `@aquienpz/asset-compressor-web` so apps that never call `compress: true` don’t pay the compressorjs + heic2any bundle cost.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                |
| --------- | ------------------------------------------------------------------- |
| `file`    | `File` \| `Blob`                                                    |
| `opts`    | [`CompressOptions`](/api/sdk/src/web/type-aliases/compressoptions/) |

## Returns

[Section titled “Returns”](#returns)

`Promise`<[`CompressResult`](/api/sdk/src/web/type-aliases/compressresult/)>

# compressImages

```ts
function compressImages(files, opts?): Promise<CompressResult[]>;
```

Defined in: packages/sdk/src/web/index.ts:314

Compress a batch of images with adaptive concurrency (navigator.hardwareConcurrency, capped at 8). Failures throw — pass `try/catch` per file if you want per-file resilience, or call `compressImage` in a loop yourself.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                                |
| --------- | ------------------------------------------------------------------- |
| `files`   | (`File` \| `Blob`)\[]                                               |
| `opts`    | [`CompressOptions`](/api/sdk/src/web/type-aliases/compressoptions/) |

## Returns

[Section titled “Returns”](#returns)

`Promise`<[`CompressResult`](/api/sdk/src/web/type-aliases/compressresult/)\[]>

# CompressOptions

```ts
type CompressOptions = {
  convertHeic?: boolean;
  convertSize?: number;
  keepOriginalDimensions?: boolean;
  maxHeight?: number;
  maxWidth?: number;
  mimeType?: "image/jpeg" | "image/webp";
  onProgress?: (stage) => void;
  quality?: number;
  strict?: boolean;
};
```

Defined in: packages/sdk/src/web/index.ts:192

Subset of compressorjs options exposed by the SDK. Matches the webapp’s `DEFAULT_COMPRESSION_OPTIONS` shape from the realtyone-cr production back-office uploader.

## Properties

[Section titled “Properties”](#properties)

### convertHeic?

[Section titled “convertHeic?”](#convertheic)

```ts
optional convertHeic?: boolean;
```

Defined in: packages/sdk/src/web/index.ts:214

Convert HEIC/HEIF inputs to JPEG via heic2any first. Default true. Has no effect on non-HEIC inputs.

***

### convertSize?

[Section titled “convertSize?”](#convertsize)

```ts
optional convertSize?: number;
```

Defined in: packages/sdk/src/web/index.ts:205

compressorjs `convertSize`: PNG > this byte count auto-converts to JPEG before the quality pass. Default 5 MB (5 \* 1024 \* 1024).

***

### keepOriginalDimensions?

[Section titled “keepOriginalDimensions?”](#keeporiginaldimensions)

```ts
optional keepOriginalDimensions?: boolean;
```

Defined in: packages/sdk/src/web/index.ts:209

Skip the resize pass (keep original dimensions). Default false.

***

### maxHeight?

[Section titled “maxHeight?”](#maxheight)

```ts
optional maxHeight?: number;
```

Defined in: packages/sdk/src/web/index.ts:200

Default 3840 (`LISTING_STANDARD_IMAGE_HEIGHT`).

***

### maxWidth?

[Section titled “maxWidth?”](#maxwidth)

```ts
optional maxWidth?: number;
```

Defined in: packages/sdk/src/web/index.ts:198

Max edge in pixels. Default 3840 (`LISTING_STANDARD_IMAGE_WIDTH`).

***

### mimeType?

[Section titled “mimeType?”](#mimetype)

```ts
optional mimeType?: "image/jpeg" | "image/webp";
```

Defined in: packages/sdk/src/web/index.ts:196

Output format. Default `"image/webp"` (`DEFAULT_IMAGE_TARGET_FORMAT`).

***

### onProgress?

[Section titled “onProgress?”](#onprogress)

```ts
optional onProgress?: (stage) => void;
```

Defined in: packages/sdk/src/web/index.ts:216

Optional progress hook. Useful for UI status indicators.

#### Parameters

[Section titled “Parameters”](#parameters)

| Parameter | Type                                                            |
| --------- | --------------------------------------------------------------- |
| `stage`   | [`CompressStage`](/api/sdk/src/web/type-aliases/compressstage/) |

#### Returns

[Section titled “Returns”](#returns)

`void`

***

### quality?

[Section titled “quality?”](#quality)

```ts
optional quality?: number;
```

Defined in: packages/sdk/src/web/index.ts:194

0..1. Default 0.80 (`LISTING_STANDARD_IMAGE_QUALITY / 100`).

***

### strict?

[Section titled “strict?”](#strict)

```ts
optional strict?: boolean;
```

Defined in: packages/sdk/src/web/index.ts:207

compressorjs strict mode. Default true.

# CompressResult

```ts
type CompressResult = {
  blob: Blob;
  originalBytes: number;
};
```

Defined in: packages/sdk/src/web/index.ts:235

## Properties

[Section titled “Properties”](#properties)

### blob

[Section titled “blob”](#blob)

```ts
blob: Blob;
```

Defined in: packages/sdk/src/web/index.ts:237

Compressed bytes wrapped as a Blob (browser-native).

***

### originalBytes

[Section titled “originalBytes”](#originalbytes)

```ts
originalBytes: number;
```

Defined in: packages/sdk/src/web/index.ts:239

Size of the source before compression, in bytes.

# CompressStage

```ts
type CompressStage = "convertingHeic" | "compressing" | "compressingKeepingDimensions";
```

Defined in: packages/sdk/src/web/index.ts:182

# WebClientOptions

```ts
type WebClientOptions = Omit<AquienpzClientOptions, "apiKey" | "signingKey">;
```

Defined in: packages/sdk/src/web/index.ts:74

Browser-safe constructor options for `@aquienpz/sdk/web`.

Identical to the root `AquienpzClientOptions` except `apiKey` and `signingKey` are **physically absent** — passing them is a TypeScript build error, not a runtime warning. In BFF-proxy mode your route handler injects the bearer header server-side; the browser never sees the long-lived key.

const aq = new AquienpzClient({ endpoint: “/api/am”, // OK: relative → same-origin BFF tenantCode: “realtyone-cr”, tenantId: 1, // apiKey: “amk\_rt\_…”, // ERROR: TS error: not assignable });

# DEFAULT_COMPRESSION_OPTIONS

```ts
const DEFAULT_COMPRESSION_OPTIONS: Required<Omit<CompressOptions, "keepOriginalDimensions" | "convertHeic" | "onProgress">>;
```

Defined in: packages/sdk/src/web/index.ts:224

Webapp-tuned defaults (LISTING\_STANDARD\_\*). These intentionally differ from `@aquienpz/asset-compressor-web`’s package-level defaults — the SDK overrides at call time.

# Browser-direct upload

> Presign on the server, PUT from the browser, register on the server — without the bytes ever transiting your API.

Three steps, and the middle one skips your server entirely.

1. **Server** presigns. It holds the key; the browser never sees it.
2. **Browser** PUTs the bytes straight to object storage.
3. **Server** registers the upload and waits for processing.

browser-direct-upload.ts

```ts
/**
 * Browser-direct upload: the bytes never touch your server.
 *
 * Your server holds the key and signs the request; the browser PUTs straight to
 * object storage. This is the pattern you want for large files — a 400 MB video
 * that transits your API costs you the bandwidth twice and the memory once.
 */
import { AquienpzClient } from "@aquienpz/sdk";


const nt = new AquienpzClient({
  endpoint: process.env.NITIDA_ENDPOINT ?? "https://assets.example.com",
  apiKey: process.env.NITIDA_RUNTIME_KEY,
  tenantCode: "demo",
  tenantId: Number(process.env.NITIDA_TENANT_ID ?? 1),
});


/** SERVER — step 1. Hand the browser a URL it may PUT to, and nothing else. */
export async function startUpload(input: {
  sha256: string;
  mime: string;
  bytes: number;
  fileName: string;
}) {
  const presign = await nt.assets.presignUploadUrl({
    ...input,
    presets: ["original", "thumb", "lg"],
  });


  // Those exact bytes already exist for this tenant: nothing needs to fly.
  if ("deduped" in presign && presign.deduped)
    return { deduped: true, presign };


  return { deduped: false, presign };
}


/**
 * SERVER — step 3, after the browser reports its PUT returned 200.
 *
 * Forward `presign.process.body` VERBATIM. It is deliberately opaque: it
 * carries the raw key, the presets and the video knobs, and rebuilding it by
 * hand is how the two halves drift apart.
 */
export async function finishUpload(processBody: Record<string, unknown>) {
  return nt.assets.processAndWait(processBody, { timeoutMs: 300_000 });
}


/**
 * BROWSER — step 2.
 *
 * ⚠️ Object storage answers this preflight ITSELF. If your origin is missing
 * from the BUCKET's CORS policy you get "network error" with every other step
 * green — and it cannot be fixed in this SDK, in your app, or in any tenant
 * setting. It is a bucket policy, and only a bucket policy.
 */
export async function putFromBrowser(url: string, file: File) {
  const res = await fetch(url, {
    method: "PUT",
    body: file,
    headers: { "Content-Type": file.type },
  });
  if (!res.ok) throw new Error(`PUT failed: ${res.status}`);
}
```

## The CORS trap

[Section titled “The CORS trap”](#the-cors-trap)

Step 2 does not talk to your API, so *your* CORS settings have no say in it. Object storage answers that preflight itself, from the **bucket’s** policy.

The symptom is unhelpful on purpose: `PUT failed: network error`, with compression, hashing and presign all reporting success. Everything you control looks fine, because the thing that rejected the request is not something you control from the app.

Caution

Applying a CORS policy usually **replaces** the whole policy rather than adding to it. List the current one and diff before you write, or you will fix your own origin by removing everyone else’s.

## Why `process.body` is opaque

[Section titled “Why process.body is opaque”](#why-processbody-is-opaque)

It carries the raw storage key, the preset ladder and the video knobs. Passing it through untouched keeps the two halves of the flow in sync; reconstructing it by hand is how they drift, and the drift shows up much later as a missing variant rather than as an error.

## When the sha already exists

[Section titled “When the sha already exists”](#when-the-sha-already-exists)

`presignUploadUrl` short-circuits with `{ deduped: true, asset }` when those exact bytes are already stored for your tenant. No PUT, no processing, no second copy — you already have the asset, so use it.

Worth knowing while testing: this is also why a **retried** upload can hide a bug in the non-deduped path. If you are verifying upload behaviour, generate genuinely unique bytes each run, or you will be exercising the dedup branch and concluding everything works.

# Compression in the browser

> What the compressor does, what it costs your bundle, and the one failure that used to make photos 24× heavier.

Compression runs in the browser, before a byte crosses the network. A raw phone photo typically shrinks 5–10×, which is bandwidth the user does not spend and storage you do not buy.

It runs in a worker on `OffscreenCanvas`, so the main thread never blocks — scrolling stays smooth while a dozen photos encode.

## What it costs your bundle

[Section titled “What it costs your bundle”](#what-it-costs-your-bundle)

Measured with `bun build --minify --splitting`, which is what a real bundler does. (Without `--splitting` the number is 1.38 MB and it is a lie — everything lands in one chunk whether or not you ever reach it.)

|                           | gzipped       | who pays                                                                                          |
| ------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| the compressor, **eager** | **4,363 B**   | everyone                                                                                          |
| `compressorjs`, lazy      | 4,994 B       | Safari < 16.4, or a failed decode                                                                 |
| `heic2any`, lazy          | **341,352 B** | each HEIC — **and only if the engine cannot decode it natively**                                  |
| `hash-wasm`               | 7,223 B       | everyone. Tree-shakes cleanly; there is no alternative, since WebCrypto has no incremental digest |

That last column is the whole design. Only 4 KB is unconditional; the expensive pieces load when something actually needs them.

## HEIC: native first

[Section titled “HEIC: native first”](#heic-native-first)

Engines that can decode HEIC do it in about **136 ms**. The WASM fallback takes roughly **1,700 ms** — and costs 341 KB to fetch first. So the native path is tried first, and the fallback only runs where it must.

That is a 12× difference on the exact file type phones produce by default, so it is worth confirming on a real device rather than in a simulator.

## The silent PNG fallback

[Section titled “The silent PNG fallback”](#the-silent-png-fallback)

`canvas.convertToBlob({ type: "image/webp" })` is allowed to **ignore you**. WebKit 26.5 returns `image/png` when asked for WebP; Chromium does not. Nothing throws, and the result still looks like an image.

Measured on an 11.9 MP photo: **PNG 21.8 MB vs JPEG 3.8 MB** — a 5.7× penalty, and 24× against a well-tuned WebP. Worse, a file labelled `.webp` that is actually a PNG breaks anything downstream that trusts the extension.

The rule this produced, and it generalises well beyond this SDK:

Label by the bytes you got, never by the format you asked for

Read the blob’s actual `type` after encoding and name the file from that. The same bug was found in five separate places once anyone looked, because every one of them assumed the request was the answer.

## When it declines

[Section titled “When it declines”](#when-it-declines)

Non-image inputs — video, PDF — skip compression entirely and upload raw. An image the engine cannot decode also uploads raw rather than failing the upload: the original arriving intact beats a clever error.

# Video and HLS

> Poster, progressive MP4, the adaptive ladder, and the AI proxy — plus the two mistakes everyone makes first.

Video is where this stops being an image CDN. A single upload produces a poster frame, a web-safe progressive MP4, an adaptive HLS ladder, and — if you ask for it — a proxy encoded for a model to watch rather than a person.

video-and-hls.ts

```ts
/**
 * Video: upload, poster, progressive MP4 and the adaptive HLS ladder.
 *
 * The two things that bite people here:
 *   1. A video is served from a STORED VARIANT, never from `/t/` (a transform
 *      URL on a stored video answers 410).
 *   2. A video finalizes ASYNCHRONOUSLY. `upload()` returns once the bytes are
 *      in and a Cloud Run Job is dispatched; the row flips to `ready` a minute
 *      or two later. Budget a real timeout — the default 5 min is a floor, not
 *      a promise.
 */
import { AquienpzClient } from "@aquienpz/sdk";


const nt = new AquienpzClient({
  endpoint: process.env.NITIDA_ENDPOINT ?? "https://assets.example.com",
  apiKey: process.env.NITIDA_RUNTIME_KEY,
  tenantCode: "demo",
  tenantId: Number(process.env.NITIDA_TENANT_ID ?? 1),
});


export async function uploadVideo(file: File) {
  const result = await nt.upload(file, {
    // `aiproxy` is the low-cost proxy an LLM analyses (5 fps, 720p, CRF 28) —
    // omit it if nothing downstream reads the video with a model.
    presets: ["original", "poster", "video", "aiproxy"],
    // A transcode plus the HLS ladder runs 1–2 min. Give it room.
    timeoutMs: 10 * 60_000,
  });


  const asset = { sha: result.sha256 };


  return {
    assetId: result.assetId,
    // The progressive MP4, off the stored variant ladder.
    mp4: nt.urlFor(asset, "video"),
    // The poster frame (sampled at 10% of the duration).
    poster: nt.urlFor(asset, "poster"),
    // The adaptive ladder's master playlist.
    hls: nt.streamingUrl(asset),
  };
}


/**
 * Download-only clips — a reel that is never streamed — should skip the HLS
 * ladder. It is a second Cloud Run Job building 240p→1080p renditions nobody
 * watches. The on-demand route still self-heals HLS if someone ever does.
 */
export async function uploadDownloadOnlyClip(file: File) {
  return nt.upload(file, {
    presets: ["original", "poster", "video"],
    video: { hls: false },
    timeoutMs: 10 * 60_000,
  });
}
```

## Video finalizes asynchronously

[Section titled “Video finalizes asynchronously”](#video-finalizes-asynchronously)

`upload()` returns once the bytes are stored and a transcode job is dispatched. The row flips to `ready` a minute or two later, when the job finishes. Anything that filters on `status === "ready"` — which is what a storefront should do — will not show the asset until then.

Budget for it. The default poll timeout is five minutes, which a 4K source can beat; pass a real `timeoutMs`.

## The four presets

[Section titled “The four presets”](#the-four-presets)

| preset    | what it is                                                  | who it is for                               |
| --------- | ----------------------------------------------------------- | ------------------------------------------- |
| `poster`  | frame sampled at 10% of the duration, WebP q80              | the `<video poster>` attribute              |
| `video`   | libx264 CRF 23, capped at 1920 wide, AAC 128k, `+faststart` | progressive playback and download           |
| `aiproxy` | 5 fps, 720p, CRF 28                                         | a model reading the video — never a human   |
| `probe`   | still JPEGs at evenly spaced offsets                        | quality sampling, thumbnails at known times |

`aiproxy` is cheap on purpose: if nothing downstream analyses the video with a model, omitting it saves you the encode.

## Two mistakes everyone makes first

[Section titled “Two mistakes everyone makes first”](#two-mistakes-everyone-makes-first)

### Using a transform URL for a stored video → `410`

[Section titled “Using a transform URL for a stored video → 410”](#using-a-transform-url-for-a-stored-video--410)

Videos come from the **stored variant**, not from `/t/`. Call `urlFor(asset, "video")`, never `transform(asset, …)`.

### Forgetting `setTenantId` → `404`

[Section titled “Forgetting setTenantId → 404”](#forgetting-settenantid--404)

The variant prefix is the tenant id **in base36**, not decimal. Tenant 10 is `/a/v/`, tenant 12 is `/c/v/`. Building a video URL without setting the tenant id produces a path that has never existed, and the CDN answers `404` — which reads like a missing file rather than a missing config.

## The ladder’s ceiling is whatever source it probes

[Section titled “The ladder’s ceiling is whatever source it probes”](#the-ladders-ceiling-is-whatever-source-it-probes)

The rungs are not fixed. The job probes the source and keeps every rung that fits inside it:

```ts
const rungs = LADDER.filter((r) => r.height <= srcHeight); // LADDER tops out at 2160p
```

Which source it probes depends on **when** the ladder is built, and that is the whole story:

| Built                   | Source                                          | Ceiling                    |
| ----------------------- | ----------------------------------------------- | -------------------------- |
| At ingest (the default) | the raw bytes you uploaded                      | **2160p from a 4K master** |
| On demand, later        | the raw if it is still there, else the `-v.mp4` | 1080p, second-generation   |

So **4K streams work**, as long as the ladder is built from the raw — which is what the automatic dispatch at ingest does. Set `video: { hls: false }` on a 4K master and you are betting on the fallback path instead.

What *is* capped unconditionally is the progressive MP4: `scale='min(1920,iw)'`. `urlFor(asset, "video")` never returns more than 1080p, whatever you uploaded. 4K is an HLS-only capability here.

A rung heavier than its own source means you are on the fallback path

Measured on one asset: the 1080p rung came out at 5090 kbps against a 4866 kbps source. That is the signature of a ladder re-encoded from the already-encoded `-v.mp4`, not of the ladder being wrong. Don’t “fix” it by trimming rungs — trimming saves about **$0.45 per month per thousand videos**, and the rungs are what make playback adapt. Rebuild it from the raw instead.

Skip the ladder for download-only clips

A reel that is downloaded and never streamed does not need HLS. Passing `video: { hls: false }` skips a whole second job that builds renditions nobody watches, and the on-demand route still self-heals HLS if someone ever streams it. The raw is kept for as long as the asset row lives — both cleanup passes skip any sha with a live row — so that self-heal normally still has the full resolution to work from.

## Playing it — the snippet everyone copies is now wrong

[Section titled “Playing it — the snippet everyone copies is now wrong”](#playing-it--the-snippet-everyone-copies-is-now-wrong)

An `.m3u8` is not a video file. A `<video src={master}>` plays only where the browser has native HLS; everywhere else it needs a Media Source Extensions player such as hls.js. So every integration starts with the same question, and the answer that the whole web repeats stopped being true in April 2026:

```ts
// ❌ the classic test — it means "Apple" to everyone who wrote it
if (video.canPlayType("application/vnd.apple.mpegurl")) { /* native */ }
```

**Chrome 147 added native HLS**, so `canPlayType` now answers `"maybe"` there too and this sends Chrome down the native branch. It does not throw — it degrades. Measured on Chromium 151 against a 17-second hero loop: `426×240` for the first \~8 seconds, because the first segment is 8.33 s long and Chrome’s adaptive logic cannot revise its guess until it finishes one. Half the loop plays at 240p, full-screen. The native branch also skips whatever progressive MP4 fallback you wrote.

Use the engine, not the codec support:

```ts
export function prefersNativeHls(video: HTMLVideoElement): boolean {
  // No native HLS at all → definitely hls.js.
  if (video.canPlayType("application/vnd.apple.mpegurl") === "") return false;
  // Apple's engine (ManagedMediaSource), or an engine with no MSE to fall back on.
  return "ManagedMediaSource" in globalThis || !("MediaSource" in globalThis);
}
```

Why not hls.js’s own recommendation

Its documented check is `canPlayType` plus `ManagedMediaSource`, which breaks iOS before 17.1: that engine has native HLS, no `ManagedMediaSource`, and no MSE. It would be routed to hls.js, which cannot start there, and the user falls all the way through to the progressive MP4. Hence the `|| !MediaSource` arm — native if the engine is Apple’s, *or* if there is no MSE to fall back on.

### When you do use hls.js, tell it not to guess

[Section titled “When you do use hls.js, tell it not to guess”](#when-you-do-use-hlsjs-tell-it-not-to-guess)

hls.js defaults to a fixed starting rung and a conservative bandwidth estimate, which is how a fast connection still opens at 240p:

```ts
new Hls({
  startLevel: -1,              // choose from the measured estimate, not a constant
  testBandwidth: true,         // measure before committing to a rung
  abrEwmaDefaultEstimate: 1_000_000,
});
```

### With Video.js you don’t write that predicate

[Section titled “With Video.js you don’t write that predicate”](#with-videojs-you-dont-write-that-predicate)

`@videojs/react` picks the engine for you. `HlsVideo` resolves to hls.js or to the browser’s native player with this rule, and `preferPlayback` defaults to `"mse"`:

```js
const useMse = Hls.isSupported() && type === M3U8 && preferPlayback !== "native";
```

That already covers the iOS < 17.1 case the naive check gets wrong — `Hls.isSupported()` is false without MSE, so it falls through to native. What it does *not* do is prefer Apple’s engine where both work: on a modern iPhone you get hls.js over `ManagedMediaSource`. That works, but native playback there buys hardware decoding, battery, and AirPlay. Pass `preferPlayback="native"` if you want it.

The hls.js tuning goes through `config`:

```tsx
import { HlsVideo } from "@videojs/react/media/hls-video";
import { Video } from "@videojs/react/video";


// Defaults open at a fixed rung before measuring anything — on a real property
// clip that meant demanding a 4.43 MiB 1080p segment first, which stalls on cellular.
const HLS_CONFIG = {
  capLevelToPlayerSize: false,
  startLevel: -1,              // pick from the measured estimate
  testBandwidth: true,         // measure before committing
  abrEwmaDefaultEstimate: 1_000_000,
};


const hls = getHlsStreamingUrl(asset);       // adaptive, up to the ladder's ceiling
const mp4 = getAssetUrl(asset, "video");     // progressive fallback, always ≤ 1080p


return isHls
  ? <HlsVideo src={hls} poster={poster} config={HLS_CONFIG} playsInline crossOrigin="anonymous" />
  : <Video    src={mp4} poster={poster} playsInline crossOrigin="anonymous" />;
```

### The first request can answer 202

[Section titled “The first request can answer 202”](#the-first-request-can-answer-202)

The ladder is built by a job. The first request for a master playlist returns `202 Accepted` while that job runs (typically 1–3 minutes for a 90-second source) and `302`s to the cached master afterwards.

Fall back on a TIMER, not on an `error` event

A `202` is a success. **No `error` event ever fires**, so a player that only swaps sources in an error handler spins forever on a ladder that is still transcoding. Race a timer against `canplay`: if the HLS source has not become playable within a few seconds, swap to the progressive MP4 — which is produced up front and is always there. Cancel the timer the instant `canplay` fires, so healthy HLS keeps its adaptive bitrate instead of being cut off.

# Quickstart

> Install, configure once, upload one image, render it responsively.

## Install

[Section titled “Install”](#install)

```bash
bun add @aquienpz/sdk @aquienpz/asset-client
```

Both packages ship the same URL builders — `@aquienpz/sdk` re-exports `@aquienpz/asset-client`. Reach for the SDK’s `AquienpzClient` only when you also **upload**; for rendering, the client alone is smaller and needs no key.

## Upload one image

[Section titled “Upload one image”](#upload-one-image)

upload-an-image.ts

```ts
/**
 * Upload one image, end to end.
 *
 * This file is REAL: `bun run check` type-checks it in CI against the same
 * workspace version of the SDK this site documents. If a signature changes,
 * the build fails instead of the website quietly lying.
 */
import { AquienpzClient } from "@aquienpz/sdk";


// The `amk_rt_*` runtime key is a WRITE key to a paid platform. It lives on the
// server, in a secret — never in a client bundle, never in `NEXT_PUBLIC_*`.
const nt = new AquienpzClient({
  endpoint: process.env.NITIDA_ENDPOINT ?? "https://assets.example.com",
  apiKey: process.env.NITIDA_RUNTIME_KEY,
  tenantCode: "demo",
  // Required: variant URLs are tenant-prefixed in base36 (`/a/v/<sha>-lg.webp`).
  tenantId: Number(process.env.NITIDA_TENANT_ID ?? 1),
});


export async function uploadImage(file: File) {
  const result = await nt.upload(file, {
    // ⚠️ "original" is non-negotiable at FIRST ingest. A variant you do not ask
    // for here can never be recovered later: the cleanup job reaps `raw/`, and
    // `regenerate()` then has nothing left to read from.
    presets: ["original", "thumb", "md", "lg"],
    // Browser-only; in Node/Bun it no-ops with a warning and uploads raw bytes.
    compress: true,
  });


  // `upload` returns ids and the canonical URL — not a full asset. Build the
  // other URLs from the sha.
  return {
    assetId: result.assetId,
    canonical: result.cdnUrl,
    display: nt.urlFor({ sha: result.sha256 }, "lg"),
  };
}
```

The runtime key is a write key

`amk_rt_*` authorises writes to a paid platform. It belongs in a server-side secret. Putting it in a client bundle — including anything named `NEXT_PUBLIC_*` — hands strangers your storage bill. The browser talks to *your* route; *your* route talks to nitida.

Ask for `original` at the first ingest

A variant you do not request on the **first** upload can never be added later: the cleanup job reaps `raw/`, and `regenerate()` then has nothing to read from. Measured on a real migration: 97 files archived “successfully”, zero recoverable. If the bytes matter, `"original"` is not optional.

## Render it

[Section titled “Render it”](#render-it)

image-urls.ts

```ts
/**
 * Build image URLs without uploading anything.
 *
 * `@aquienpz/asset-client` has no network and no key — it is pure URL
 * construction. Import it directly when all you do is render.
 */
import {
  getTransformSrcSet,
  getTransformUrl,
  setCdnBase,
  setTenantId,
  type TransformWidth,
} from "@aquienpz/asset-client";


// The builders read PROCESS-GLOBAL config. Pin it once where your helpers live,
// so every module that imports a builder is configured.
setCdnBase(process.env.NEXT_PUBLIC_NITIDA_CDN ?? "https://8ok.uk");
setTenantId(Number(process.env.NEXT_PUBLIC_NITIDA_TENANT_ID ?? 1));


// Lock the output format to your project's policy rather than using `auto`.
const FORMAT = "webp" as const;


/**
 * ⚠️ The width MUST be on the unsigned ladder. Any other width is an HTTP 400
 * at the edge — that is a deliberate DoS guard, not a bug. Importing
 * `TransformWidth` turns an off-ladder width into a COMPILE error, which is
 * where you want to find out.
 */
export const imageUrl = (sha: string, width: TransformWidth) =>
  getTransformUrl({ sha }, { format: FORMAT, width });


export const imageSrcSet = (sha: string, widths: readonly TransformWidth[]) =>
  getTransformSrcSet({ sha }, widths, { format: FORMAT });


/** Fixed-aspect cards and thumbnails want a cover crop. */
export const thumbUrl = (sha: string, width: TransformWidth) =>
  getTransformUrl(
    { sha },
    { format: FORMAT, width, fit: "cover", gravity: "auto" },
  );
```

### Widths are a ladder, not a number

[Section titled “Widths are a ladder, not a number”](#widths-are-a-ladder-not-a-number)

A width outside `TRANSFORM_WIDTHS` answers **HTTP 400** at the edge. That is a deliberate guard — an open resize endpoint is a denial-of-service amplifier — not a bug to work around. Import the `TransformWidth` type and an off-ladder width becomes a compile error instead of a production 400:

```plaintext
160 · 240 · 256 · 320 · 400 · 480 · 600 · 640 · 800 · 960
1080 · 1200 · 1280 · 1440 · 1600 · 1920 · 2560 · 3840
```

## Two URL shapes, and they are not interchangeable

[Section titled “Two URL shapes, and they are not interchangeable”](#two-url-shapes-and-they-are-not-interchangeable)

|                                                            | shape                                         | tenant-scoped |
| ---------------------------------------------------------- | --------------------------------------------- | ------------- |
| **Stored variants** — `urlFor`, `srcSetFor`, `cdnUrl`      | `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>` | yes           |
| **On-the-fly transforms** — `transform`, `transformSrcSet` | `<cdn>/t/<dsl>/<sha>.<ext>`                   | no            |

Transforms are content-addressed by sha and resize from the source on demand, so they carry no tenant segment. Variants are pre-generated per tenant and do. Using `/t/` for a **stored video** answers `410` — see [Video and HLS](/guides/video-and-hls/).