@nitida/sdk 0.27.0 → 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;
 };
@@ -227,6 +243,7 @@ export type {
 export {
   accessMessage,
   assertPublic,
+  assertSha,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver,
@@ -253,12 +270,14 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   iteratePaletteSwatches,
   PRESET_EXT,
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS,
   relativeLuminance,
   resolveSlot,
   resolveSlots,
@@ -268,6 +287,7 @@ export {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  toRequestablePresets,
 } from "@nitida/asset-client";
 
 // ---------------------------------------------------------------------------
@@ -530,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}`),
@@ -1018,6 +1043,22 @@ const DEFAULT_UPLOAD_PRESETS: RequestablePreset[] = ["original"];
 export type UploadResult = {
   assetId: string;
   sha256: string;
+  /**
+   * The SAME 16-hex prefix an `AssetDTO` carries, so the result of an upload can
+   * be handed straight to any URL builder.
+   *
+   * ⭐ It exists because it did not, and that cost a real 404. A Haiku agent
+   * evaluating the SDK on 2026-08-23 did the most natural thing there is —
+   * `transform(await upload(file), { width: 1280 })` — and got
+   * `https://8ok.uk/t/width=1280/undefined.webp`. The builders read `sha`; this
+   * type only had `sha256`. TypeScript caught it; running through `bun`, or in
+   * plain JS, nothing did.
+   *
+   * The guard (`assertSha`) is the backstop. This field is the actual fix: the
+   * obvious call is now the correct one, which is worth more than a good error
+   * message about the wrong one.
+   */
+  sha: string;
   cdnUrl: string;
 };
 
@@ -1279,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
@@ -1317,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;
@@ -1563,6 +1605,7 @@ export class NitidaClient {
       return {
         assetId: existing.id,
         sha256: sha,
+        sha: sha.slice(0, 16),
         cdnUrl: this.urlFor(existing, this.bestPresetForAsset(existing, mime)),
       };
     }
@@ -1588,6 +1631,7 @@ export class NitidaClient {
       return {
         assetId: presign.asset.id,
         sha256: sha,
+        sha: sha.slice(0, 16),
         cdnUrl: this.urlFor(presign.asset, this.defaultPresetForMime(mime)),
       };
     }
@@ -1638,6 +1682,7 @@ export class NitidaClient {
     return {
       assetId,
       sha256: sha,
+      sha: sha.slice(0, 16),
       cdnUrl: this.urlFor(final, this.bestPresetForAsset(final, mime)),
     };
   }

package/src/server/index.ts

@@ -96,6 +96,7 @@ export {
   type AssetVariant,
   accessMessage,
   assertPublic,
+  assertSha,
   bestTextContrast,
   type ComposeMarketingComposition,
   type ComposeMarketingOptions,
@@ -128,6 +129,7 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
@@ -139,6 +141,7 @@ export {
   PRESET_SHORT,
   type PresignUploadUrlOptions,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS,
   type RegenerateResult,
   type RequestablePreset,
   type ResolveSlotOptions,
@@ -162,6 +165,7 @@ export {
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  toRequestablePresets,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,

package/src/web/index.ts

@@ -113,6 +113,7 @@ export {
   type AssetVariant,
   accessMessage,
   assertPublic,
+  assertSha,
   bestTextContrast,
   type ComposeMarketingComposition,
   type ComposeMarketingOptions,
@@ -145,6 +146,7 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
@@ -155,6 +157,7 @@ export {
   PRESET_SHORT,
   type PresignUploadUrlOptions,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS,
   type RegenerateResult,
   type RequestablePreset,
   type ResolveSlotOptions,
@@ -178,6 +181,7 @@ export {
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  toRequestablePresets,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,