NitidaClient

Defined in: packages/sdk/src/server/index.ts:72

Server-safe NitidaClient — same runtime as the root class, but the constructor type enforces apiKey so misconfiguration is a TS build error, not a runtime 401.

Extends

NitidaClient

Constructors

Constructor

new NitidaClient(opts): NitidaClient;

Defined in: packages/sdk/src/server/index.ts:73

Parameters

Parameter	Type
`opts`	`ServerClientOptions`

Returns

NitidaClient

Overrides

NitidaClient.constructor

Properties

assets

readonly assets: AssetsApi;

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

Inherited from

NitidaClient.assets

opts

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.

Inherited from

NitidaClient.opts

slots

readonly slots: SlotsApi;

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

Inherited from

NitidaClient.slots

usage

readonly usage: UsageApi;

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

Inherited from

NitidaClient.usage

Accessors

tenantSegment

Get Signature

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

Inherited from

NitidaClient.tenantSegment

Methods

srcSetFor()

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`<`AssetDTO`, `"sha"` \| `"presets"`>

Returns

string

Inherited from

NitidaClient.srcSetFor

streamingUrl()

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:

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`<`AssetDTO`, `"sha"`>
`opts`	`Omit`<`TransformOptions`, `"format"`>

Returns

string

Inherited from

NitidaClient.streamingUrl

transform()

Call Signature

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.

Parameters

Parameter	Type
`asset`	`Pick`<`AssetDTO`, `"sha"`>
`opts?`	`TransformOptions`

Returns

string

See

TransformOptions for the full param matrix.

Inherited from

NitidaClient.transform

Call Signature

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.

Parameters

Parameter	Type
`asset`	`Pick`<`AssetDTO`, `"sha"`>
`opts`	`TransformOptions`
`signOpts`	{ `sign`: `true`; } & `SignTransformOptions`

Returns

Promise<string>

See

TransformOptions for the full param matrix.

Inherited from

NitidaClient.transform

transformSrcSet()

Call Signature

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`<`AssetDTO`, `"sha"`>
`widths`	`number`[]
`extraOpts?`	`Omit`<`TransformOptions`, `"width"`>

Returns

string

Inherited from

NitidaClient.transformSrcSet

Call Signature

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`<`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`<`TransformOptions`, `"width"`>
`signOpts`	{ `sign`: `true`; } & `SignTransformOptions`

Returns

Promise<string>

Inherited from

NitidaClient.transformSrcSet

transformVideo()

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-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`<`AssetDTO`, `"sha"`>
`opts`	`TransformOptions`

Returns

string

Inherited from

NitidaClient.transformVideo

upload()

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`>
`opts`	`UploadOptions`

Returns

Promise<UploadResult>

Examples

Deliver an image on a site (the responsive ladder)

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`

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

Raw bytes need an explicit MIME

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

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

Inherited from

NitidaClient.upload

urlFor()

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`<`AssetDTO`, `"sha"`>	`undefined`
`preset`	`VariantPreset`	`"lg"`

Returns

string

Inherited from

NitidaClient.urlFor