@nitida/sdk 0.27.1 → 0.28.0

package/AGENTS.md

@@ -101,6 +101,22 @@ await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeco
 - **`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
 

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, 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, 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<{

package/dist/index.js

@@ -53,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,
@@ -67,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(/\/+$/, "");
@@ -199,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}`),
@@ -572,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"));
@@ -581,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;
@@ -860,6 +868,7 @@ export {
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
+  REQUESTABLE_PRESETS2 as REQUESTABLE_PRESETS,
   TRANSFORM_WIDTHS,
   accessMessage,
   assertPublic,
@@ -890,6 +899,7 @@ export {
   hasPreset2 as hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache2 as invalidateSlotCache,
+  isRequestablePreset2 as isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
@@ -901,6 +911,7 @@ export {
   setCdnBase2 as setCdnBase,
   setTenantId2 as setTenantId,
   signAccessUrl,
-  signTransformUrl
+  signTransformUrl,
+  toRequestablePresets2 as toRequestablePresets
 };
 //# sourceMappingURL=index.js.map