@nitida/sdk 0.25.2 → 0.26.0

package/src/expo/index.ts

@@ -26,6 +26,33 @@
  *   const { assetId } = await upload.start();
  *   await aq.slots.bind("storefront.tour.video", { assetId, preset: "video" });
  *
+ * ⚠️ THIS PATH PUTS A RUNTIME KEY ON THE DEVICE. Read before shipping.
+ *
+ * `createExpoUploader` reads `client.opts.apiKey` and hands it to the native
+ * session as its `authToken` (see below — it is four lines, and they are the
+ * whole story). The native uploader talks to the API directly, so it needs a
+ * credential the OS can replay hours later from a background task. There is no
+ * BFF in that loop to inject one.
+ *
+ * That is the opposite of what every other surface here does, and the opposite
+ * of what `@nitida/sdk/web` chose when it hit the SAME constraint: `/web`
+ * deliberately does NOT expose the multipart uploader, because it needs a raw
+ * `authToken` a BFF cannot supply. `/expo` exposes it anyway, because
+ * background-surviving uploads are the entire reason a native session exists.
+ *
+ * So, concretely, an `amk_rt_*` key in your app bundle is readable by anyone
+ * who unzips the IPA/APK, and it is a WRITE key to a paid platform.
+ *
+ *   - Uploading big video in the background is worth it to you ⇒ use this, and
+ *     scope the key to one tenant so a leak is contained and revocable.
+ *   - It is not ⇒ build the client from `@nitida/sdk/web` pointed at your own
+ *     route and call `aq.upload(file)`. No key on the device. You lose survival
+ *     across backgrounding and OS kill; the upload dies with the JS thread.
+ *
+ * The real fix — a BFF-minted short-lived token the native session can carry —
+ * is not built. It is the same gap `/web` documents. Ask; there is no public
+ * tracker.
+ *
  * Peer dep: `@aquienpz/asset-uploader-expo` (lazy — apps that don't
  * use the mobile SDK skip the install).
  * @module @nitida/sdk/expo
@@ -44,9 +71,11 @@ export type ExpoUploadOptions = Omit<
 
 /**
  * Spawn a native-backed `UploadTask` bound to a configured client.
- * Inherits the client's endpoint / api key / tenant scope; caller only
- * has to supply the file input + any per-upload tuning (partSize,
- * concurrency).
+ *
+ * ⚠️ It reaches into the client for `apiKey` and uses it as the session's
+ * `authToken`, so the client you pass MUST have been built with a real runtime
+ * key — which means that key is on the device. See the module header for what
+ * that costs and what the alternative is.
  */
 export function createExpoUploader(
   client: NitidaClient,

package/src/index.ts

@@ -48,6 +48,7 @@ import {
   getVideoTransformUrl,
   hasPreset,
   invalidateSlotCache,
+  type RequestablePreset,
   type ResolveSlotOptions,
   resolveSlot,
   resolveSlots,
@@ -57,6 +58,7 @@ import {
   setCdnBase,
   setTenantId,
   type TransformOptions,
+  type VariantEntryPreset,
   type VariantPreset,
 } from "@nitida/asset-client";
 
@@ -203,6 +205,7 @@ export type {
   AssetVariant,
   HlsRung,
   PaletteSwatch,
+  RequestablePreset,
   ResolveSlotOptions,
   SignedTransformOptions,
   SlotDTO,
@@ -213,6 +216,7 @@ export type {
   TransformGravity,
   TransformOptions,
   TransformWidth,
+  VariantEntryPreset,
   VariantPreset,
 } from "@nitida/asset-client";
 export {
@@ -464,8 +468,11 @@ export type PresignUploadUrlOptions = {
   /**
    * Variant ladder to generate after `/assets/process`. Defaults to
    * `["original"]` server-side when omitted — same contract as `aq.upload`.
+   *
+   * {@link RequestablePreset}, not {@link VariantPreset}: `hls` and `mp3` are
+   * things a variant can BE, never things you can ask for, and asking is a 400.
    */
-  presets?: VariantPreset[];
+  presets?: RequestablePreset[];
   /**
    * Pre-compression size of the source (useful when the browser ran
    * compressorjs / heic2any before computing `bytes`). Recorded
@@ -646,7 +653,7 @@ class AssetsApi {
    */
   async regenerate(
     assetId: string,
-    opts: { presets?: VariantPreset[] } = {},
+    opts: { presets?: RequestablePreset[] } = {},
   ): Promise<RegenerateResult> {
     const r = await fetch(
       endpointHref(this.opts, `/assets/${assetId}/regenerate`),
@@ -919,7 +926,7 @@ export type UploadOptions = {
    * this option — those go to the upload pipeline raw.
    *
    * @see {@link CompressOptions}
-   * @see https://github.com/espaciofuturoio/aquienpz/tree/main/packages/sdk#client-side-compression-browsers
+   * @see https://nitida.gofuture.space/guides/advanced/ — client-side compression
    */
   compress?: boolean | CompressOptions;
   /**
@@ -945,8 +952,12 @@ export type UploadOptions = {
    * Idempotent: you can always add missing variants later via
    * `aq.assets.regenerate(id, { presets: [...] })`. The platform
    * stores the source so regeneration doesn't require re-uploading.
+   *
+   * {@link RequestablePreset}, not {@link VariantPreset}. `hls` and `mp3` are
+   * produced FOR you — the ladder when a video transcodes, the mp3 alongside
+   * any audio original — and asking for either is a 400.
    */
-  presets?: VariantPreset[];
+  presets?: RequestablePreset[];
   /**
    * Max time to wait for the asset to transition to `ready` (or `failed`)
    * after dispatch. Default `5 * 60_000` (5 min). Bump higher for large
@@ -973,8 +984,16 @@ export type UploadOptions = {
   video?: UploadVideoOptions;
 };
 
-/** Default preset set the SDK sends to `/assets/upload-url` when the caller omits `presets`. */
-const DEFAULT_UPLOAD_PRESETS: VariantPreset[] = ["original"];
+/**
+ * Default preset set the SDK sends to `/assets/upload-url` when the caller
+ * omits `presets`.
+ *
+ * Typed `RequestablePreset[]`, not `VariantPreset[]` — it is a REQUEST. The
+ * distinction caught this very line the moment it was introduced: it was the
+ * wrong type here, and a `VariantPreset[]` default could have carried `hls`
+ * into a request that answers 400.
+ */
+const DEFAULT_UPLOAD_PRESETS: RequestablePreset[] = ["original"];
 
 export type UploadResult = {
   assetId: string;

package/src/server/index.ts

@@ -75,49 +75,93 @@ export class NitidaClient extends BaseNitidaClient {
   }
 }
 
+// ---------------------------------------------------------------------------
+// This subpath MIRRORS THE ROOT. Every export of `@nitida/sdk` is here.
+//
+// It is a COMPLETE entry point, not an additive module — a Node consumer is
+// told to import from here and must never have to reach past it. It did:
+// `getHlsLadder` was on the root and missing here, an example in the docs
+// imported it from `/server`, and an agent evaluating the SDK got a
+// SyntaxError at RUNTIME. Measured on 2026-08-21, this list was short by 28
+// of the root's 72 — the whole palette family, every slot helper, the HLS
+// ladder helpers and the preset constants.
+//
+// The completeness is now ASSERTED by scripts/check-published-doc-symbols.ts,
+// which also owns the deny list: an omission has to be justified there, in
+// writing, or the build fails. Do not hand-edit this list to be shorter.
+// ---------------------------------------------------------------------------
 export {
   type AssetDTO,
+  type AssetPalette,
   type AssetVariant,
+  bestTextContrast,
   type ComposeMarketingComposition,
   type ComposeMarketingOptions,
   type ComposeMarketingResult,
   type ComposeMarketingSegment,
   type CompressOptions,
-  // URL builders & related types (re-export from asset-client via root).
   computeVariantDimensions,
+  configureSlotResolver,
+  contrastRatio,
   extractAssetSha,
+  getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getCdnBase,
+  getHlsLadder,
   getHlsStreamingUrl,
+  getPaletteBlurBackground,
+  getPaletteCssVars,
   getSignedTransformUrl,
   getTenantId,
+  getTextColorForBackground,
   getTransformSrcSet,
   getTransformUrl,
   getVideoTransformUrl,
+  type HlsRung,
   hasPreset,
+  hlsLadderAlignment,
+  invalidateSlotCache,
+  iteratePaletteSwatches,
+  mimeFromFileName,
   type NitidaClientOptions,
+  type PaletteSwatch,
+  PRESET_EXT,
+  PRESET_LONG,
+  PRESET_MAX_DIM,
+  PRESET_SHORT,
   type PresignUploadUrlOptions,
+  pickAmbientBackground,
   type RegenerateResult,
+  type RequestablePreset,
   type ResolveSlotOptions,
+  relativeLuminance,
+  resolveSlot,
+  resolveSlots,
   type SignedTransformOptions,
   type SlotDTO,
   type SlotHistoryEntry,
   type SlotResolution,
   serializeTransform,
+  setCdnBase,
   setTenantId,
   signTransformUrl,
+  TRANSFORM_WIDTHS,
   type TransformEffect,
   type TransformFit,
   type TransformFormat,
   type TransformGravity,
   type TransformOptions,
+  type TransformWidth,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,
+  type UploadVideoOptions,
   type UsageDailyPoint,
   type UsagePerKey,
   type UsageSnapshot,
   type UsageWindow,
+  type VariantEntryPreset,
   type VariantPreset,
 } from "..";

package/src/web/index.ts

@@ -88,43 +88,97 @@ export class NitidaClient extends BaseNitidaClient {
   }
 }
 
-// Re-export the rest of the surface (URL builders, types, etc.) so
-// browser consumers can satisfy 100% of their needs through this
-// single subpath.
+// ---------------------------------------------------------------------------
+// This subpath MIRRORS THE ROOT — which is what the sentence that used to sit
+// here already promised: "browser consumers can satisfy 100% of their needs
+// through this single subpath". Measured on 2026-08-21, it did not: this list
+// was short by 37 of the root's 72, including every palette helper, every slot
+// helper, the HLS ladder helpers, the preset constants and `setTenantId` —
+// without which a browser app cannot build a video URL at all.
+//
+// ONE deliberate omission, and it is enforced as such rather than left to
+// memory: `NitidaClientOptions`. That is the root options type and it CARRIES
+// `apiKey`. The entire point of this subpath is that the apiKey-bearing shape
+// is unreachable from browser code; `WebClientOptions` above is the one to
+// use. Exporting the other from here is a mixed message even though the
+// constructor would still reject it.
+//
+// The mirror and that single denial are both ASSERTED by
+// scripts/check-published-doc-symbols.ts. Adding a new omission means adding a
+// written reason there, or the build fails.
+// ---------------------------------------------------------------------------
 export {
   type AssetDTO,
+  type AssetPalette,
   type AssetVariant,
+  bestTextContrast,
+  type ComposeMarketingComposition,
+  type ComposeMarketingOptions,
+  type ComposeMarketingResult,
+  type ComposeMarketingSegment,
   type CompressOptions as ClientCompressOptions,
   computeVariantDimensions,
+  configureSlotResolver,
+  contrastRatio,
   extractAssetSha,
+  getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getCdnBase,
+  getHlsLadder,
   getHlsStreamingUrl,
+  getPaletteBlurBackground,
+  getPaletteCssVars,
   getSignedTransformUrl,
+  getTenantId,
+  getTextColorForBackground,
   getTransformSrcSet,
   getTransformUrl,
   getVideoTransformUrl,
+  type HlsRung,
   hasPreset,
+  hlsLadderAlignment,
+  invalidateSlotCache,
+  iteratePaletteSwatches,
+  mimeFromFileName,
+  type PaletteSwatch,
+  PRESET_EXT,
+  PRESET_LONG,
+  PRESET_MAX_DIM,
+  PRESET_SHORT,
+  type PresignUploadUrlOptions,
+  pickAmbientBackground,
   type RegenerateResult,
+  type RequestablePreset,
   type ResolveSlotOptions,
+  relativeLuminance,
+  resolveSlot,
+  resolveSlots,
   type SignedTransformOptions,
   type SlotDTO,
   type SlotHistoryEntry,
   type SlotResolution,
   serializeTransform,
+  setCdnBase,
+  setTenantId,
   signTransformUrl,
+  TRANSFORM_WIDTHS,
   type TransformEffect,
   type TransformFit,
   type TransformFormat,
   type TransformGravity,
   type TransformOptions,
+  type TransformWidth,
   type UploadOptions,
   type UploadResult,
+  type UploadUrlResult,
+  type UploadVideoOptions,
   type UsageDailyPoint,
   type UsagePerKey,
   type UsageSnapshot,
   type UsageWindow,
+  type VariantEntryPreset,
   type VariantPreset,
 } from "..";
 
@@ -138,9 +192,8 @@ export {
 // the BFF doesn't expose). The cleaner story is:
 //
 //   - Files ≤50MB → `aq.upload(file)` (single PUT, atomic, BFF-friendly)
-//   - Files >50MB → roadmap item for v0.18 (BFF-minted short-lived token
-//     + resumable multipart). Track at
-//     https://github.com/espaciofuturoio/aquienpz/issues
+//   - Files >50MB → resumable multipart behind a BFF-minted short-lived
+//     token is not exposed yet. Ask us; there is no public tracker.
 //
 // Apps that need `UploadTask` directly today should depend on
 // `@aquienpz/asset-uploader-web` themselves once it's published.