@nitida/sdk 0.27.1 → 0.28.0

package/src/index.ts

@@ -48,6 +48,8 @@ import {
   getVideoTransformUrl,
   hasPreset,
   invalidateSlotCache,
+  isRequestablePreset,
+  REQUESTABLE_PRESETS,
   type RequestablePreset,
   type ResolveSlotOptions,
   resolveSlot,
@@ -58,6 +60,7 @@ import {
   setCdnBase,
   setTenantId,
   type TransformOptions,
+  toRequestablePresets,
   type VariantEntryPreset,
   type VariantPreset,
 } from "@nitida/asset-client";
@@ -114,12 +117,25 @@ export type NitidaClientOptions = {
    * Tenant's HMAC signing key for transform URLs (Phase 3). Required
    * only when calling `aq.transform(asset, opts, { sign: true })`.
    *
-   * 32 random bytes, generated server-side on tenant creation; fetch
-   * via `POST /admin/projects/:code/rotate-signing-key`, which needs a
-   * SYSTEM-scope credential the platform operator holds — your own admin key
-   * answers `403 SYSTEM_KEY_REQUIRED`. Ask for it. **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.
+   * 32 random bytes, generated server-side on tenant creation.
+   *
+   * **Where you get it: the response to your project's creation, once.**
+   * `POST /admin/projects` returns `signingKey` next to the three API keys,
+   * and the console shows it in the same panel. It is shown there and nowhere
+   * else — save it with the keys.
+   *
+   * **Never saw one?** Projects created before 2026-08-23 were not handed it,
+   * and no endpoint shows you the current one. If you have not signed any URLs
+   * yet — true of every project that has not shipped private assets — ask for
+   * a rotation: with nothing in flight it invalidates nothing and is free. If
+   * you already have signed URLs circulating, ask for the current key instead.
+   *
+   * Either way it is one request to the platform operator:
+   * `POST /admin/projects/:code/rotate-signing-key` needs a SYSTEM-scope
+   * credential, and your own admin key answers `403 SYSTEM_KEY_REQUIRED`.
+   *
+   * **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.
    */
   signingKey?: string;
 };
@@ -254,12 +270,14 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   iteratePaletteSwatches,
   PRESET_EXT,
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS,
   relativeLuminance,
   resolveSlot,
   resolveSlots,
@@ -269,6 +287,7 @@ export {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  toRequestablePresets,
 } from "@nitida/asset-client";
 
 // ---------------------------------------------------------------------------
@@ -531,7 +550,12 @@ export type ComposeMarketingResult = {
 class AssetsApi {
   constructor(private readonly opts: NitidaClientOptions) {}
 
-  /** Look up an asset by full sha256 (64 hex). Returns null on 404. */
+  /**
+   * Look up an asset by sha256. Accepts the full 64-hex digest that
+   * `upload()` returns as `sha256`, or the 16-char short prefix that appears
+   * in every CDN URL. Returns null on 404; throws with a message naming the
+   * expected shape if the string is neither form.
+   */
   async byHash(sha256: string): Promise<AssetDTO | null> {
     const r = await fetch(
       endpointHref(this.opts, `/assets/by-hash/${sha256}`),
@@ -1296,7 +1320,7 @@ export class NitidaClient {
     if (!this.opts.signingKey) {
       throw new Error(
         "aq.transform({ sign: true }) requires `signingKey` in NitidaClientOptions. " +
-          "No signingKey on this client. The key is minted by POST /admin/projects/:code/rotate-signing-key, which needs a system-scope credential the platform operator holds — your own admin key gets 403 SYSTEM_KEY_REQUIRED, so ask for it. Then pass it to the SDK constructor on a SERVER-side instance only.",
+          "No signingKey on this client. It is returned ONCE, in the response that creates your project (POST /admin/projects → `signingKey`, next to the three API keys; the console shows it in the same panel). If you never saw one — projects created before 2026-08-23 were not handed it — ask the platform operator to rotate: with no signed URLs in flight that invalidates nothing and is free. If you DO have signed URLs circulating, ask for the current key instead, because rotating would kill them. Then pass it to the SDK constructor on a SERVER-side instance only.",
       );
     }
     // Signed path — custom (off-ladder) widths allowed. Empty opts → no
@@ -1334,7 +1358,8 @@ export class NitidaClient {
     if (!signOpts?.sign) return getTransformSrcSet(asset, widths, extraOpts);
     if (!this.opts.signingKey) {
       throw new Error(
-        "aq.transformSrcSet({ sign: true }) requires `signingKey` in NitidaClientOptions.",
+        "aq.transformSrcSet({ sign: true }) requires `signingKey` in NitidaClientOptions. " +
+          "It was returned ONCE, by the response that created your project (POST /admin/projects → `signingKey`). See the `signingKey` docs on NitidaClientOptions.",
       );
     }
     const key = this.opts.signingKey;

package/src/server/index.ts

@@ -129,6 +129,7 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
@@ -140,6 +141,7 @@ export {
   PRESET_SHORT,
   type PresignUploadUrlOptions,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS,
   type RegenerateResult,
   type RequestablePreset,
   type ResolveSlotOptions,
@@ -163,6 +165,7 @@ export {
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  toRequestablePresets,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,

package/src/web/index.ts

@@ -146,6 +146,7 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
@@ -156,6 +157,7 @@ export {
   PRESET_SHORT,
   type PresignUploadUrlOptions,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS,
   type RegenerateResult,
   type RequestablePreset,
   type ResolveSlotOptions,
@@ -179,6 +181,7 @@ export {
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  toRequestablePresets,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,