# NitidaClient

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

## Extended by

- [`NitidaClient`](/api/nitida/sdk/server/classes/nitidaclient/)
- [`NitidaClient`](/api/nitida/sdk/web/classes/nitidaclient/)

## Constructors

### Constructor

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

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

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `opts` | [`NitidaClientOptions`](/api/nitida/sdk/type-aliases/nitidaclientoptions/) |

#### Returns

`NitidaClient`

## Properties

### assets

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

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

***

### opts

```ts
readonly opts: NitidaClientOptions;
```

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

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

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

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

***

### usage

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

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

## Accessors

### tenantSegment

#### Get Signature

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

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

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

##### Returns

`string`

## Methods

### srcSetFor()

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

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

Build a responsive srcSet across the available image presets.

#### Parameters

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

#### Returns

`string`

***

### streamingUrl()

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

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

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
background 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

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

#### Returns

`string`

***

### transform()

#### Call Signature

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

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

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

## 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
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

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

##### Returns

`string`

##### See

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

#### Call Signature

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

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

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

## 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
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

| Parameter | Type |
| ------ | ------ |
| `asset` | [`Pick`](/api/nitida/sdk/react/-internal-/type-aliases/pick/)\<[`AssetDTO`](/api/nitida/sdk/type-aliases/assetdto/), `"sha"`\> |
| `opts` | [`TransformOptions`](/api/nitida/sdk/type-aliases/transformoptions/) |
| `signOpts` | \{ `sign`: `true`; \} & [`SignTransformOptions`](/api/nitida/sdk/type-aliases/signtransformoptions/) |

##### Returns

`Promise`\<`string`\>

##### See

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

***

### transformSrcSet()

#### Call Signature

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

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

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

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

##### Returns

`string`

#### Call Signature

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

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

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

| Parameter | Type |
| ------ | ------ |
| `asset` | [`Pick`](/api/nitida/sdk/react/-internal-/type-aliases/pick/)\<[`AssetDTO`](/api/nitida/sdk/type-aliases/assetdto/), `"sha"`\> |
| `widths` | ( \| `96` \| `128` \| `160` \| `180` \| `240` \| `256` \| `320` \| `400` \| `480` \| `600` \| `640` \| `800` \| `960` \| `1080` \| `1200` \| `1280` \| `1440` \| `1600` \| `1920` \| `2560` \| `3840`)[] |
| `extraOpts` | [`Omit`](/api/nitida/asset-client/-internal-/type-aliases/omit/)\<[`TransformOptions`](/api/nitida/sdk/type-aliases/transformoptions/), `"width"`\> |
| `signOpts` | \{ `sign`: `true`; \} & [`SignTransformOptions`](/api/nitida/sdk/type-aliases/signtransformoptions/) |

##### Returns

`Promise`\<`string`\>

***

### transformVideo()

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

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

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
background job for video encoding (vs the inline pipeline for
images).

On the first request the route returns **202 Accepted** with
`Retry-After: 10` while the encode runs (typically 5-30 s for a
short clip). The response body includes `outputUrl` which is the
eventual CDN URL — poll the same transform URL after the
retry-after window to get a 302 redirect to it.

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

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

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

#### Returns

`string`

***

### upload()

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

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

Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-storage 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 ~24 h grace window on the uploaded bytes
closes — measured once as "97 files archived successfully, zero recoverable".

#### Parameters

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

#### Returns

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

#### Examples

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

```ts
import { NitidaClient } from "@nitida/sdk/server";

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

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

***

### urlFor()

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

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

Build the canonical CDN URL deterministically from sha + preset.

#### Parameters

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

#### Returns

`string`