AquienpzClient

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

Extended by

Constructors

Constructor

new AquienpzClient(opts): AquienpzClient;

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

Parameters

Parameter	Type
`opts`	`AquienpzClientOptions`

Returns

AquienpzClient

Properties

assets

readonly assets: AssetsApi;

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

opts

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

readonly slots: SlotsApi;

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

usage

readonly usage: UsageApi;

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

Accessors

tenantSegment

Get Signature

get tenantSegment(): string;

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

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

Returns

string

Methods

srcSetFor()

srcSetFor(asset): string;

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

Build a responsive srcSet across the available image presets.

Parameters

Parameter	Type
`asset`	`Pick`<`AssetDTO`, `"sha"` \| `"presets"`>

Returns

string

streamingUrl()

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:

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

Parameter	Type
`asset`	`Pick`<`AssetDTO`, `"sha"`>
`opts`	`Omit`<`AssetDTO`, `"format"`>

Returns

string

transform()

Call Signature

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)

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.

Parameters

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

Returns

string

See

TransformOptions for the full param matrix.

Call Signature

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)

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.

Parameters

Parameter	Type
`asset`	`Pick`<`AssetDTO`, `"sha"`>
`opts`	`SignedTransformOptions`
`signOpts`	{ `sign`: `true`; }
`signOpts.sign`	`true`

Returns

Promise<string>

See

TransformOptions for the full param matrix.

transformSrcSet()

Call Signature

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

Parameter	Type
`asset`	`Pick`<`AssetDTO`, `"sha"`>
`widths`	`number`[]
`extraOpts?`	`Omit`<`TransformOptions`, `"width"`>

Returns

string

Call Signature

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

Parameter	Type
`asset`	`Pick`<`AssetDTO`, `"sha"`>
`widths`	`number`[]
`extraOpts`	`Omit`<`AssetDTO`, `"width"`>
`signOpts`	{ `sign`: `true`; }
`signOpts.sign`	`true`

Returns

Promise<string>

transformVideo()

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 /

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

upload()

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

Parameter	Type
`input`	\| `File` \| `Blob` \| `Uint8Array`<`ArrayBufferLike`>
`opts`	`UploadOptions`

Returns

Promise<UploadResult>

Examples

Deliver an image on a site (the responsive ladder)

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`

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 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()

urlFor(asset, preset?): string;

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

Build the canonical CDN URL deterministically from sha + preset.

Parameters

Parameter	Type	Default value
`asset`	`Pick`<`AssetDTO`, `"sha"`>	`undefined`
`preset`	`VariantPreset`	`"lg"`

Returns

string