@nitida/sdk 0.27.0 → 0.28.0

package/AGENTS.md

@@ -94,11 +94,29 @@ await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeco
 - **Seven URL builders throw** rather than hand you a doomed URL — `getAssetUrl`,
   `getAssetSrcSet`, `getTransformUrl`, `getTransformSrcSet`,
   `getVideoTransformUrl`, `getHlsStreamingUrl`, `getSignedTransformUrl` — but
-  only when the value you pass carries `visibility`. `{ sha }` alone is never
-  refused.
+  only when the value you pass says `visibility: "private"`. A DTO that says
+  `"public"`, or a bare `{ sha }`, is never refused — and this is a DIFFERENT
+  rule from the missing-preset fallback below, which is about presets, not
+  privacy.
 - **`exp` is mandatory**; revocation is *"within a minute"* (60 s TTL at the edge).
 - **The signing key is a backend secret** — it mints URLs for every private
   asset the tenant owns.
+- **⭐ Where the signing key comes from: the response that CREATED your
+  project, once.** `POST /admin/projects` returns `signingKey` next to the
+  three API keys, and the console shows it in the same panel. Nothing else
+  hands it out — `GET /admin/projects/:code` does **not** include it. If it is
+  lost, the only endpoint that returns a key is
+  `POST /admin/projects/:code/rotate-signing-key`, which **invalidates every
+  URL already signed** and needs the system-scope key the platform operator
+  holds. A tenant with nothing signed yet can rotate for free; a live one
+  cannot, which is why you save it at creation.
+- **⭐ Already have a project and never saw a signing key?** Then you never got
+  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, ask us to
+  rotate: with nothing in flight, rotation invalidates nothing and is free.**
+  If you already have signed URLs circulating, ask us for the current key
+  instead. This is the wall the T5 agent hit, and the sentence that was
+  missing.
 
 ## Two ways an image gets smaller, and only one of them is yours to call
 
@@ -118,18 +136,25 @@ So for an API/agent upload there is nothing to "turn on": you were never going
 to compress the raw, and delivery is already optimised two ways.
 
 ```ts
-// Ask for the rungs you will actually render…
-await aq.upload(file, { presets: ["original", "thumb", "md", "lg"] });
+await aq.upload(file);
+aq.transform(asset, { width: 1280, format: "webp" });  // → /t/…, generated once, cached after
 
-// …or upload bare and let the transform route make them on demand:
-aq.transform(asset, { width: 1280, format: "webp" });   // → /t/…, cached after the first hit
+// Only for a rung you KNOW will be rendered over and over:
+await aq.upload(file, { presets: ["original", "thumb"] });
 ```
 
 **`presets` defaults to `["original"]`** — a bare upload stores the raw and no
 rendition. Since 2026-08-22 that is no longer a trap: when the DTO says a preset
 was never materialised, `getAssetUrl` / `urlFor` **fall back to `/t/`** instead
 of returning a URL that 404s. You still get optimised bytes; you just pay the
-first encode. Prefer naming the presets when you know what you will render.
+first encode.
+
+**On demand is the default, and it is the right one.** A variant exists because
+somebody asked for it; we do not manufacture sizes on the chance that they might
+be wanted. Name presets at upload only for a rung you *know* will be rendered
+over and over — a card thumbnail on every listing page — where paying the encode
+once up front beats paying it once lazily. For everything else, upload bare and
+let `/t/` do it.
 
 ⚠️ `getAssetSrcSet` deliberately does **not** fall back — a srcSet promises
 pixel widths and a transform cannot keep that promise on a source smaller than

package/README.md

@@ -259,8 +259,11 @@ const heroes = await aq.slots.resolveMany([
   "storefront.home.tile-2",
 ]);
 
-// Lower-level operations.
+// Lower-level operations. `byHash` takes the full 64-hex sha256 that
+// `upload()` returns as `.sha256`, OR its 16-char prefix — the short form
+// that appears inside every CDN URL. Both resolve to the same asset.
 const asset = await aq.assets.byHash("3c…<64 hex>…");
+const same = await aq.assets.byHash("3c8f1a20b7d94e05"); // 16-char prefix ✓
 const { assets, nextCursor } = await aq.assets.list({ limit: 50 });
 
 // Uploads — hash-deduped; returns the canonical v2 URL immediately.
@@ -894,6 +897,29 @@ as they specify the same params.
 
 Every tenant has an HMAC-SHA256 signing key — 32 random bytes, generated
 on tenant creation.
+
+> **Where you get it: the response that created your project, once.**
+> `POST /admin/projects` returns `signingKey` next to the three API keys, and
+> the console shows it in the same panel. Save it with the keys — nothing else
+> hands it out. In particular `GET /admin/projects/:code` does **not** return
+> it, and neither does any tenant-scoped endpoint.
+>
+> **Your project already exists and you never saw a signing key?** Then you
+> never got one: projects created before 2026-08-23 were not handed it, and
+> there is no endpoint that shows you the current one. This is the exact wall
+> to hit, so here is the way through it:
+>
+> - **If you have not signed any URLs yet** — which is true of every project
+>   that has not shipped private assets — ask us to rotate. Rotation returns a
+>   key, and with nothing in flight it invalidates nothing. It is free.
+> - **If you already have signed URLs in circulation**, rotation kills them.
+>   Ask us for the current key instead; we can read it.
+>
+> Either way it is one request to us, because
+> `POST /admin/projects/:code/rotate-signing-key` needs the system-scope key
+> the platform operator holds — your own admin key answers
+> `403 SYSTEM_KEY_REQUIRED`.
+
 Optionally enable `strict_transforms = true` to reject unsigned URLs
 with a 401 — useful when transform URLs leak from a private surface
 (internal admin, b2b portal) and you don't want third parties
@@ -905,7 +931,8 @@ const aq = new NitidaClient({
   apiKey:     process.env.AQUIENPZ_API_KEY!,
   tenantCode: "your-tenant",
   tenantId:   42,
-  // Fetch via GET /admin/projects/your-tenant; do NOT ship to the browser.
+  // Handed to you once, by the response that created the project.
+  // do NOT ship to the browser.
   signingKey: process.env.AQUIENPZ_SIGNING_KEY!,
 });
 
@@ -1304,7 +1331,7 @@ API key tiers:
 | `aq.slots` | `bind(key, {assetId, preset})` | Admin rebind |
 | `aq.slots` | `unbind(key)` | Remove binding |
 | `aq.slots` | `invalidateCache(key?)` | After admin rebind |
-| `aq.assets` | `byHash(sha)` / `byHashes([])` | Lookup |
+| `aq.assets` | `byHash(sha)` / `byHashes([])` | Lookup — full 64-hex sha **or** its 16-char prefix |
 | `aq.assets` | `list({limit, cursor})` | Paginated |
 | `aq.assets` | `get(id)` | Full DTO |
 | `aq.assets` | `patchMetadata(id, {…})` | Merge JSON |

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ResolveSlotOptions, SlotResolution, SlotDTO, VariantPreset, AssetDTO, AssetVariant, RequestablePreset, TransformOptions, SignedTransformOptions } from '@nitida/asset-client';
-export { AssetDTO, AssetPalette, AssetVariant, HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, PaletteSwatch, RequestablePreset, ResolveSlotOptions, SignAccessOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, VariantPreset, VisibilityHint, accessMessage, assertPublic, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl } from '@nitida/asset-client';
+export { AssetDTO, AssetPalette, AssetVariant, HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, PaletteSwatch, REQUESTABLE_PRESETS, RequestablePreset, ResolveSlotOptions, SignAccessOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, VariantPreset, VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets } from '@nitida/asset-client';
 
 /**
  * Which audio uploads already play everywhere — the single source of truth for
@@ -119,12 +119,25 @@ 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;
 };
@@ -319,7 +332,12 @@ type ComposeMarketingResult = {
 declare class AssetsApi {
     private readonly opts;
     constructor(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.
+     */
     byHash(sha256: string): Promise<AssetDTO | null>;
     /** Bulk lookup by sha256s. */
     byHashes(hashes: string[]): Promise<{
@@ -587,6 +605,22 @@ type UploadOptions = {
 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;
 };
 type SlotHistoryEntry = {

package/dist/index.js

@@ -26,6 +26,7 @@ function isUniversallyPlayableAudio(mime) {
 import {
   accessMessage,
   assertPublic,
+  assertSha,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver as configureSlotResolver2,
@@ -52,12 +53,14 @@ import {
   hasPreset as hasPreset2,
   hlsLadderAlignment,
   invalidateSlotCache as invalidateSlotCache2,
+  isRequestablePreset as isRequestablePreset2,
   iteratePaletteSwatches,
   PRESET_EXT,
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS as REQUESTABLE_PRESETS2,
   relativeLuminance,
   resolveSlot as resolveSlot2,
   resolveSlots as resolveSlots2,
@@ -66,7 +69,8 @@ import {
   setTenantId as setTenantId2,
   signAccessUrl,
   signTransformUrl,
-  TRANSFORM_WIDTHS
+  TRANSFORM_WIDTHS,
+  toRequestablePresets as toRequestablePresets2
 } from "@nitida/asset-client";
 function endpointUrl(opts, path, searchParams) {
   const endpoint = opts.endpoint.replace(/\/+$/, "");
@@ -198,7 +202,12 @@ var AssetsApi = class {
     this.opts = opts;
   }
   opts;
-  /** 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) {
     const r = await fetch(
       endpointHref(this.opts, `/assets/by-hash/${sha256}`),
@@ -571,7 +580,7 @@ var NitidaClient = class {
     }
     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 \u2014 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."
+        "aq.transform({ sign: true }) requires `signingKey` in NitidaClientOptions. No signingKey on this client. It is returned ONCE, in the response that creates your project (POST /admin/projects \u2192 `signingKey`, next to the three API keys; the console shows it in the same panel). If you never saw one \u2014 projects created before 2026-08-23 were not handed it \u2014 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."
       );
     }
     return getSignedTransformUrl(asset, opts, this.opts.signingKey) ?? Promise.resolve(this.urlFor(asset, "lg"));
@@ -580,7 +589,7 @@ var NitidaClient = class {
     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 \u2192 `signingKey`). See the `signingKey` docs on NitidaClientOptions."
       );
     }
     const key = this.opts.signingKey;
@@ -752,6 +761,7 @@ var NitidaClient = class {
       return {
         assetId: existing.id,
         sha256: sha,
+        sha: sha.slice(0, 16),
         cdnUrl: this.urlFor(existing, this.bestPresetForAsset(existing, mime))
       };
     }
@@ -768,6 +778,7 @@ var NitidaClient = class {
       return {
         assetId: presign.asset.id,
         sha256: sha,
+        sha: sha.slice(0, 16),
         cdnUrl: this.urlFor(presign.asset, this.defaultPresetForMime(mime))
       };
     }
@@ -810,6 +821,7 @@ var NitidaClient = class {
     return {
       assetId,
       sha256: sha,
+      sha: sha.slice(0, 16),
       cdnUrl: this.urlFor(final, this.bestPresetForAsset(final, mime))
     };
   }
@@ -856,9 +868,11 @@ export {
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
+  REQUESTABLE_PRESETS2 as REQUESTABLE_PRESETS,
   TRANSFORM_WIDTHS,
   accessMessage,
   assertPublic,
+  assertSha,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver2 as configureSlotResolver,
@@ -885,6 +899,7 @@ export {
   hasPreset2 as hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache2 as invalidateSlotCache,
+  isRequestablePreset2 as isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
@@ -896,6 +911,7 @@ export {
   setCdnBase2 as setCdnBase,
   setTenantId2 as setTenantId,
   signAccessUrl,
-  signTransformUrl
+  signTransformUrl,
+  toRequestablePresets2 as toRequestablePresets
 };
 //# sourceMappingURL=index.js.map