@nitida/sdk 0.20.0

package/skills/nitida-sdk/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: nitida-sdk
+description: How to consume the nitida media platform (formerly aquienpz) (@nitida/sdk + @nitida/asset-client, CDN 8ok.uk) from an app — build image/video URLs, resolve stored refs, migrate an app off a legacy CDN, and provision a tenant. Use when wiring images/videos through aquienpz, debugging 400/404/410 on 8ok.uk URLs, or onboarding a new tenant. Captures the gotchas that bit real migrations (base36 video prefix, /t/ vs /v/, the width ladder, audio, the 0-cdn build gate).
+---
+
+# Consuming the nitida media platform
+
+> Durable source of truth: `aquienpz` repo `docs/SDK_CONSUMER_GUIDE.md`. This is a local copy for skill activation; update the repo doc when these learnings change.
+
+The platform stores assets in R2 and serves them through the CDN **`https://8ok.uk`**.
+Apps are **external consumers**: install the npm packages, never vendor neo's in-tree copies.
+
+```bash
+bun add @nitida/sdk @nitida/asset-client
+```
+
+Both packages export the same URL builders (`@nitida/sdk` re-exports `@nitida/asset-client`). For plain URL-building in a Next.js app, importing from `@nitida/asset-client` is enough; use `@nitida/sdk`'s `AquienpzClient` only when you also upload.
+
+## 1. Configure once at module load
+
+The URL builders read **process-global** config. Pin it where your helpers live (a `lib/aquienpz-images.ts`), so every Server/Client Component that imports a builder is configured:
+
+```ts
+import { setCdnBase, setTenantId } from "@nitida/asset-client";
+
+const CDN = process.env.NEXT_PUBLIC_AQUIENPZ_CDN || "https://8ok.uk";
+const TENANT_ID = Number(process.env.NEXT_PUBLIC_AQUIENPZ_TENANT_ID) || /* your id */ 0;
+
+setCdnBase(CDN);        // default is already "https://8ok.uk"
+setTenantId(TENANT_ID); // REQUIRED for video URLs (base36 variant prefix) — see §3
+```
+
+`NEXT_PUBLIC_*` so the tenant id reaches the client bundle (hero/about videos render client-side). The runtime read-only consumer needs only these public vars — the `amk_rt_*` runtime key is for **uploads** (server-only), not for building URLs.
+
+## 2. Image URLs — `getTransformUrl` / `getTransformSrcSet`
+
+On-the-fly transforms. **Lock `format` to your project's policy** (these projects use `webp`, never `auto`/`avif`):
+
+```ts
+import {
+  getTransformUrl, getTransformSrcSet, TRANSFORM_WIDTHS, type TransformWidth,
+} from "@nitida/asset-client";
+
+const FORMAT = "webp" as const;
+
+export const imgUrl = (sha: string, width: TransformWidth, extra?) =>
+  getTransformUrl({ sha }, { format: FORMAT, width, ...extra });
+
+export const imgSrcSet = (sha: string, widths: readonly TransformWidth[], extra?) =>
+  getTransformSrcSet({ sha }, widths, { format: FORMAT, ...extra });
+
+// cover-crop for fixed-aspect cards/thumbs:
+const COVER_CROP = { fit: "cover", gravity: "auto" } as const;
+```
+
+Output URL shape: `https://8ok.uk/t/format=webp,width=640/<sha16>.webp`.
+
+⚠️ **Widths MUST be on the unsigned ladder** `TRANSFORM_WIDTHS` (`160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840`). Any other width → **HTTP 400** at the edge (DoS guard). The `TransformWidth` type makes an off-ladder width a compile error — import the type, don't hardcode magic numbers. (For a one-off custom width you'd need signed URLs; not used here.)
+
+## 3. Video URLs — `getAssetUrl(asset, "video")`  ← the #1 gotcha
+
+Videos are served from the **stored variant**, NOT a transform:
+
+```ts
+import { getAssetUrl, setTenantId } from "@nitida/asset-client";
+
+export function videoUrl(sha: string, tenantId = TENANT_ID): string {
+  if (!sha) return "";
+  setTenantId(tenantId);                 // sets the base36 variant prefix
+  return getAssetUrl({ sha }, "video") ?? "";
+}
+```
+
+Output: `https://8ok.uk/<tenantId.toString(36)>/v/<sha16>-v.mp4`.
+
+**Do NOT:**
+- ❌ Use `getVideoTransformUrl` — that builds a `/t/...` transform URL, which **410s** for a stored video sha. (`getVideoTransformUrl` is for on-the-fly re-encodes, a different feature.)
+- ❌ Hand-roll the path with the decimal tenant id. The path segment is **base36**: `tenantId.toString(36)`. **Tenant 10 → `/a/v/`**, and the decimal `/10/v/` **404s**. This is invisible for tenants ≤ 9 (`8`→`8`, `9`→`9`) and bit a real migration only at tenant 10. Always delegate to `getAssetUrl` so the encoding can't drift.
+
+**Audio IS supported (updated 2026-07-01 — verify against the SDK types, this used to say "not supported").** The platform now recognizes `kind: "image" | "video" | "document" | "audio" | "other"` and ships an **`mp3`** variant preset (`VariantPreset` in `@nitida/asset-client`). Upload raw audio bytes with an explicit audio MIME so it stores as `kind:"audio"` (not `"other"`): `await aq.upload(bytes, { contentType: "audio/mpeg", fileName: "track.mp3" })`. Uploads are hash-deduped (byte-identical re-uploads return the existing sha — that's *byte* dedup, NOT semantic "find a similar track"). `aq.upload` also accepts an `audioTrack` on video-composition calls. Serve via the `mp3` preset / `original`. (Legacy `.m4a/.wav` with no matching pipeline still fall back to `original` raw bytes.) Confirm the current preset/kind list in `node_modules/@nitida/asset-client/dist/index.d.ts` before relying on a specific ext.
+
+## 3b. Keeping the ORIGINAL bytes (backup, not delivery) ← learned the hard way 2026-08-07
+
+If you are uploading to **archive** something (not just to serve it), three server behaviours decide whether you actually can get the bytes back. All three verified against `apps/asset-manager/src` in the `aquienpz` repo, after a 97-file backup ran "successfully" and produced **zero** recoverable originals.
+
+**1. `original` is written only if you ask for it.** In `features/assets/process.routes.ts`:
+
+```ts
+const effectivePresets: string[] = body.presets ?? ["original"];
+const wantsOriginal = effectivePresets.includes("original");
+```
+
+- Omit `presets` entirely → **original only**, no ladder (passthrough).
+- Pass `["thumb"]` → thumb only, **no original**. The bytes you PUT are not retrievable.
+- For a backup you want `presets: ["original", "thumb"]`.
+
+⚠️ The migration precedent in consumer repos (`migrate-*-images.ts`) uses `["thumb"]` because its goal is *delivery*. Copying it into a backup script silently produces a non-backup.
+
+**2. Building the `original` URL client-side is possible but easy to get wrong** (this section said "impossible" until 2026-08-15 — see the correction below). The server key is:
+
+```ts
+variantKey(tenantId, sha256, "original", ext)
+  → `${tenantPrefix(tenantId)}/v/${shortenSha(sha)}-o.${ext}`
+//    ext = body.rawKey.split(".").pop()   ← the UPLOADED file's extension
+```
+
+The client's `PRESET_EXT.original` is the literal `"bin"`, so `getAssetUrl({sha}, "original")` **without `mime`** emits `-o.bin` while a PNG is really stored at `-o.png` → 404, always.
+
+> ⚠️ **CORRECTED 2026-08-15 — the advice below used to be "read it from `aq.assets.variants()`",
+> and that method is now the one that fails.** Measured against the live deployment while building
+> `neo/apps/media-harness`:
+>
+> - **`aq.assets.variants(id)` returns `[]`** — with a runtime key *and* with an admin key — while
+>   the database row for the same asset holds two variants. Believing the empty array makes a
+>   healthy asset look like it is missing everything.
+> - **`getAssetUrl` now takes the asset's `mime`** and resolves a real extension:
+>   `getAssetUrl({ sha, mime }, "original")` → `…-o.webp`, HTTP **200**. The old `-o.bin` sentinel
+>   only appears when you omit `mime`.
+> - **…but the extension the SERVER stored comes from the uploaded FILENAME, not the mime.**
+>   `variantKey(..., ext)` uses `rawKey.split(".").pop()`. For JPEG these disagree —
+>   `image/jpeg` → `jpeg` while a camera writes `.jpg`. Measured: `…-o.jpeg` **404**, `…-o.jpg` 200.
+>
+> ⇒ **What to do:** existence from `dto.presets` (the compact codes, always populated — use
+> `hasPreset`), URL from `getAssetUrl({sha, mime}, "original")` with the **uploaded filename's
+> extension** swapped in if it differs, and then **verify with a real HEAD before you rely on it**.
+> Reference implementation: `apps/media-harness/scripts/seed-fixtures.ts` (`resolveOriginalUrl`).
+> (`getAssetUrl` stays correct for `video`/`poster`, whose extensions are fixed.)
+
+**3. Re-uploading does NOT repair a missing preset.** Ingest dedupes by hash and returns `deduped: true` with the existing asset; no variants are regenerated. To add a preset to an existing asset use `regenerate`, which MERGES:
+
+```ts
+await aq.assets.regenerate(assetId, { presets: ["original"] });
+```
+
+⚠️ **There is a time window.** `admin.routes.ts` notes that once the cleanup job reaps `raw/`, regenerate reads from `variants/o.<ext>` — which is exactly what's missing. **If the first ingest didn't request `original`, the raw bytes may already be unrecoverable.** In the 2026-08-07 run, `regenerate({presets:["original"]})` returned without error and the `original` variant still did not appear — consistent with `raw/` already being gone. Get `original` right on the FIRST ingest.
+
+**Verify, don't assume.** Round-trip every archived file: download the `original` URL from the API and compare its SHA-256 to the local file. "97 uploaded, 0 failed" was true and meaningless — all 97 were unrecoverable.
+
+| Goal | presets | Where the URL comes from |
+|---|---|---|
+| Deliver images on a site | `["thumb"]` (+ what you need) | `getTransformUrl` / `getTransformSrcSet` |
+| **Archive the source file** | **`["original", "thumb"]`** | **`aq.assets.variants(assetId)` → `preset:"original"`** |
+
+## 3c. PLAYING a video — HLS, and the snippet that went stale in April 2026
+
+`getHlsStreamingUrl({ sha })` returns a `master.m3u8`. **That is not a video file**: it plays
+natively only where the browser has HLS built in, and everywhere else it needs an MSE player
+(hls.js, or Video.js's `@videojs/http-streaming`). So every integration has to pick a branch, and
+the test the entire web repeats is now wrong:
+
+```ts
+if (video.canPlayType("application/vnd.apple.mpegurl")) { /* native */ }   // ← the bug
+```
+
+**Chrome 147 (April 2026) added native HLS**, so `canPlayType` answers `"maybe"` there and this
+sends Chrome down the native branch. It doesn't throw — it **degrades silently**. Measured on
+Chromium 151 against a real 17 s hero loop: **426×240 for the first ~8 s** (the first segment is
+8.33 s, and Chrome's ABR can't revise its guess until one finishes), i.e. half the loop at 240p
+full-screen. That branch also skips whatever progressive-MP4 fallback you wrote.
+
+**Branch on the ENGINE, not on codec support:**
+
+```ts
+function prefersNativeHls(video: HTMLVideoElement): boolean {
+  if (video.canPlayType("application/vnd.apple.mpegurl") === "") return false;  // no native HLS
+  return "ManagedMediaSource" in globalThis || !("MediaSource" in globalThis);
+}
+```
+
+⚠️ **Don't use hls.js's own recommended check** (`canPlayType` + `ManagedMediaSource`): it breaks
+iOS < 17.1, which has native HLS, no `ManagedMediaSource` and **no MSE** — it would be routed to
+hls.js, which cannot start there, and fall through to the MP4. The `|| !MediaSource` arm is what
+covers it: native if the engine is Apple's **OR** if there is no MSE to fall back on.
+
+**When you use hls.js, stop it guessing** — the defaults are how a fast connection still opens at
+240p: `{ startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 }`.
+
+**The first request can answer `202`** while the Cloud Run Job builds the ladder (1–3 min for a
+90 s source), then `302`s to the cached master. Keep the progressive MP4 as the fallback `<source>`
+so a player pointed at HLS too early still shows something.
+
+**With Video.js you don't write that predicate.** `@videojs/react`'s `HlsVideo` resolves the engine
+itself — `useMse = Hls.isSupported() && type === M3U8 && preferPlayback !== "native"`, and
+`preferPlayback` defaults to `"mse"`. That already covers iOS < 17.1 (no MSE ⇒ falls to native).
+What it does NOT do is prefer Apple's engine where both work: a modern iPhone gets hls.js over
+`ManagedMediaSource`. Pass `preferPlayback="native"` to buy hardware decode / battery / AirPlay.
+hls.js tuning goes in the `config` prop:
+
+```tsx
+const HLS_CONFIG = { capLevelToPlayerSize: false, startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 };
+<HlsVideo src={getHlsStreamingUrl(asset)} config={HLS_CONFIG} poster={poster} playsInline crossOrigin="anonymous" />
+```
+
+⚠️ **Fall back to the MP4 on a TIMER, never on an `error` event.** A `202` is a success: no `error`
+ever fires, so an error-only handler spins forever while the ladder transcodes. Race a timer against
+`canplay`, and cancel it the moment `canplay` fires so healthy HLS keeps its adaptive bitrate.
+
+### 4K is an HLS-only capability
+
+**"Progressive" = one file, one resolution, fixed at encode time** (`-v.mp4`): the browser downloads
+it end-to-end and plays as it goes, and if the connection degrades it stalls — there is nothing to
+step down to. **HLS = many files**: the same video cut into segments and encoded at several rungs,
+so the player switches mid-playback. That is the whole difference, and it is why only one of them
+can carry 4K.
+
+The ladder is not fixed at 1080p — the job probes the source and keeps every rung that fits
+(`LADDER.filter(r => r.height <= srcHeight)`, up to **2160p**). What it probes decides the ceiling:
+
+| Ladder built | Source | Ceiling |
+|---|---|---|
+| At ingest (automatic, unless `video.hls === false`) | the raw bytes you uploaded | **2160p from a 4K master** |
+| On demand later | the raw if present, else the `-v.mp4` | 1080p, second-generation |
+
+The progressive MP4 is capped unconditionally (`scale='min(1920,iw)'`), so `getAssetUrl(sha,"video")`
+never exceeds 1080p whatever you uploaded. A rung that weighs *more* than its own source (measured:
+5090 vs 4866 kbps) is the signature of the fallback path, not of a broken ladder.
+
+## 4. Resolving a stored reference — `extractAssetSha`
+
+When a stored value is already an `8ok.uk` URL, pull its sha:
+
+```ts
+import { extractAssetSha } from "@nitida/asset-client";
+const sha = extractAssetSha(storedUrl); // → "e0ef99988f4a3c9b" | null
+```
+
+A robust app resolver tries, in order: an explicit `sha` on the row → a migrated-metadata blob → a migration-map lookup by old URL → `extractAssetSha` → raw fallback.
+
+## 5. Migrating an app OFF a legacy CDN onto aquienpz
+
+Pattern proven on carniceria, novatibas, sueños (all off `cdn.espaciofuturo.io`):
+
+1. **Re-ingest is required, not a host rename.** Legacy hashes (64-hex sha256) ≠ aquienpz (16-hex sha). You must **fetch each legacy asset's bytes and re-upload** to the tenant (SDK server client + `amk_rt_*` key), producing a NEW sha. Emit an idempotent `old-URL → { sha, w, h, blur, kind }` map (`scripts/asset-migration-map.json`). Upload presets: images→`thumb`, videos→`poster`+`video`. Dedupe by sha; checkpoint (re-runnable).
+2. **Regenerate metadata** (`blur`/`w`/`h`/`aspectRatio`) from the uploaded asset (`assets.get`) — don't carry legacy values.
+3. **Render: bake resolved `8ok.uk` URLs at author time.** Do NOT `import` the map JSON into runtime code — its old-URL *keys* ship into the client/server bundle and fail a "0 legacy refs in built output" check. Resolve at build/author time and write the literal `8ok.uk` URL.
+4. **Next.js**: add `8ok.uk` to `images.remotePatterns`. With `images.unoptimized: true`, pass the CDN srcSet straight through. With Next optimization ON, set `unoptimized` **per slot** for CDN-backed images to avoid paying for double optimization.
+5. **Completeness sweep before declaring done**: `grep cdn-host` must be 0 in (a) rendered HTML of every route, (b) serialized/embedded JSON payloads (this is where a stale ref hides even when the *image* renders correctly), (c) JSON-LD / OG / preconnect, (d) any **DB mirror table** (an app DB's `assets`/asset tables are easy to miss), and (e) **cached API responses** (a CDN/data cache can persist a pre-cutover payload across deploys → bust the tag, don't assume redeploy clears it). "Images load from 8ok.uk" is NOT sufficient proof.
+
+## 6. Provisioning a new tenant (ops / WS-0)
+
+```bash
+# Secrets live in GCP Secret Manager, project `naye-tours`:
+#   PLATFORM_DATABASE_URL (platform Neon), ASSET_AUTH_SECRET (better-auth)
+# 1) Insert tenant rows (idempotent) into the platform Neon:
+#    SELECT MAX(id)+1 FROM public.tenants;  -- pick next id
+#    INSERT public.tenants (id, code, vertical, name) ...
+#    INSERT public.tenant_config (tenant_id, code, vertical, display_name,
+#                                 storefront_origins, brand_json, feature_flags, qdrant_tenant_id) ...
+# 2) Mint keys (prints runtime/admin/ci ONCE — store immediately):
+cd apps/asset-manager
+PLATFORM_DATABASE_URL=… ASSET_AUTH_SECRET=… bun run scripts/bootstrap-project.ts <tenant-code>
+```
+
+- Endpoint = the asset-manager Cloud Run URL. Verify: `GET /usage` with `Authorization: Bearer <amk_rt_*>` + `X-Tenant-Code: <code>` → `{ "tenant": { "id": N } }`.
+- The `@aquienpz/tenant-config` HTTP layer **caches tenant lookups for 60s** — a fresh tenant resolves in services within a minute (the `bootstrap` script reads the DB directly, so it works immediately).
+- Asset-only consumers (a storefront with its own catalog DB) can skip the Qdrant/voice/scraper steps in `docs/TENANT_ONBOARDING.md` — only the two tenant rows + keys + `storefront_origins` are needed.
+
+## Quick reference
+
+| Need | Call | URL shape |
+|---|---|---|
+| Responsive image | `getTransformSrcSet({sha}, widths, {format:'webp'})` | `/t/format=webp,width=W/<sha>.webp` |
+| Single image | `getTransformUrl({sha}, {format:'webp', width})` | same |
+| Cover-crop card | `…, { fit:'cover', gravity:'auto' }` | `/t/fit=cover,gravity=auto,format=webp,width=W/<sha>.webp` |
+| **Video** | `getAssetUrl({sha}, 'video')` (+ `setTenantId`) | `/<tid b36>/v/<sha>-v.mp4` |
+| Poster | `getAssetUrl({sha}, 'poster')` | `/<tid b36>/v/<sha>-p.webp` |
+| Sha from URL | `extractAssetSha(url)` | — |
+
+Variant preset short codes: `thumb=q, sm=s, md=m, lg=l, xl=x, original=o, poster=p, video=v`. Exts: images `webp`, video `mp4`.
+
+## 7. Browser-direct uploads — three things that only fail in a real browser
+
+Measured 2026-08-15 building `neo/apps/media-harness`, the bench for this SDK. Run it
+(`bun run scripts/verify-run.ts`) before debugging any of these by hand.
+
+1. **The PUT goes browser → R2, so R2 answers the CORS preflight.** An origin missing from the
+   BUCKET's policy cannot be fixed in your app, in this SDK, or in `tenant_config.storefront_origins`
+   — those govern the API, not the PUT. Symptom: `R2 PUT failed: network error` with compression,
+   hashing and presign all green. Fix in `aquienpz/scripts/setup-r2-cors.sh`, and ⚠️ `cors set`
+   **REPLACES** the whole policy — list it and diff before applying.
+2. **A VIDEO answers `processAndWait` immediately, then transcodes.** `/assets/process` dispatches a
+   Cloud Run Job and answers `{ ok: true, kind: "video", assetId, status: "processing", dispatch }`;
+   the SDK then polls that id until `ready`. Budget for it — a transcode plus the HLS ladder runs
+   1–2 min, so pass a `timeoutMs` of at least `300_000`. (Until 2026-08-16 the response carried **no
+   `assetId`** and the call threw `"process returned no assetId"`, so no video ever registered
+   through the kit; the bytes still reached R2, which is what made it invisible.)
+3. **A video never gets an `original` variant.** `/assets/process` filters video presets through
+   `{poster, video, aiproxy, probe}` before dispatch, so `"original"` is silently dropped even when
+   you ask for it. If you need the source bytes back, archive them under a **non-video key** (e.g.
+   `clip.mp4.bin`), which takes the passthrough branch and stores them verbatim.
+
+| Symptom | Cause |
+|---|---|
+| **400** on an image URL | width not on `TRANSFORM_WIDTHS` ladder |
+| **410** on a video URL | used `/t/` (transform) for a stored video — use `getAssetUrl(...,'video')` |
+| **404** on a video URL | decimal tenant prefix (`/10/v/`) instead of base36 (`/a/v/`) — call `setTenantId` + `getAssetUrl`. Tenant 12 → `/c/v/` |
+| `process returned no assetId` | fixed 2026-08-16 — you are on an `asset-manager` older than that deploy, §7.2 |
+| `waitReady timeout` on a video | a transcode + HLS ladder takes 1–2 min; the default `timeoutMs` is 5 min but a 4K source can beat it. Raise it, §7.2 |
+| `R2 PUT failed: network error` | your origin is not in the R2 BUCKET's CORS policy, §7.1 |
+| `aq.assets.variants()` returns `[]` | current deployment does not populate it, even for admin keys. Use `dto.presets` + `hasPreset` |
+| `tenant_not_found` from a service | tenant rows missing, or the 60s tenant-config cache is stale |
+| `original` 404s | (a) never written — `presets` omitted `"original"` at ingest, or the asset is a VIDEO (always dropped, §7.3); (b) `getAssetUrl(...,"original")` called WITHOUT `mime` → the `-o.bin` sentinel; (c) called WITH `mime` but the object was stored under the uploaded filename's extension (`-o.jpg`, not `-o.jpeg`). See §3b — HEAD it |
+| "uploaded OK" but nothing to restore | `["thumb"]`-style presets store no original; verify by SHA-256 round-trip, not by upload count — see §3b |
+| audio won't serve | stored as `kind:"other"` — re-upload with an explicit `contentType:"audio/mpeg"` so it's `kind:"audio"` + gets the `mp3` preset (audio IS supported as of 2026-07-01; see §3) |
+
+> Source of truth for deeper detail: `docs/ASSET_MANAGER_V2.md`, `docs/CLIENT_OPERATIONS.md`, `docs/TENANT_ONBOARDING.md`, and `packages/asset-client/src/{transform.ts,index.ts}`.

package/src/expo/index.ts

@@ -0,0 +1,76 @@
+/**
+ * @nitida/sdk/expo — native multipart uploads for React Native / Expo.
+ *
+ * Wraps `@aquienpz/asset-uploader-expo`'s `UploadTask`, which delegates
+ * the actual byte transfer to a native background session (URLSession
+ * on iOS, WorkManager on Android). The upload survives:
+ *   - JS thread freezing
+ *   - App backgrounding
+ *   - OS-initiated kill (low-memory, user swiping away)
+ *   - Network blips (retries with backoff)
+ *
+ * Usage:
+ *
+ *   import { createExpoUploader, listResumableSessions } from "@nitida/sdk/expo";
+ *
+ *   const aq = new AquienpzClient({ ... });
+ *
+ *   // Resume any uploads from a prior app launch on boot.
+ *   const resumable = await listResumableSessions();
+ *   // ...show a banner offering to resume them
+ *
+ *   const upload = createExpoUploader(aq, {
+ *     file: { uri: assetUri, mime: "video/mp4", name: "tour.mp4" },
+ *   });
+ *   upload.on("progress", ({ ratio }) => setProgress(ratio));
+ *   const { assetId } = await upload.start();
+ *   await aq.slots.bind("storefront.tour.video", { assetId, preset: "video" });
+ *
+ * Peer dep: `@aquienpz/asset-uploader-expo` (lazy — apps that don't
+ * use the mobile SDK skip the install).
+ * @module @nitida/sdk/expo
+ */
+
+import {
+  UploadTask,
+  type UploadTaskOptions,
+} from "@aquienpz/asset-uploader-expo";
+import type { AquienpzClient } from "..";
+
+export type ExpoUploadOptions = Omit<
+  UploadTaskOptions,
+  "tenantCode" | "endpoint" | "authToken"
+>;
+
+/**
+ * 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).
+ */
+export function createExpoUploader(
+  client: AquienpzClient,
+  options: ExpoUploadOptions,
+): UploadTask {
+  const access = client as unknown as {
+    opts: { endpoint: string; apiKey: string; tenantCode: string };
+  };
+  return new UploadTask({
+    ...options,
+    endpoint: access.opts.endpoint,
+    authToken: access.opts.apiKey,
+    tenantCode: access.opts.tenantCode,
+  });
+}
+
+export type {
+  UploadEvents,
+  UploadFileInput,
+  UploadSessionState,
+  UploadTaskOptions,
+} from "@aquienpz/asset-uploader-expo";
+export {
+  cancelResumableSession,
+  listResumableSessions,
+  UploadTask,
+} from "@aquienpz/asset-uploader-expo";