@nomideusz/svelte-media 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 0.6.0 — 2026-08-14
+
+Second pass of the same job 0.5.0 started: the parts of "handling images" both
+apps still owned move here, so an app keeps only what is actually its own —
+bucket names, copy, and (for yoga) what a Google Places reference costs.
+
+### Added
+- **`adapterFromEnv(env, options?)`** — the S3_*/`MEDIA_ROOT` wiring both apps
+  had hand-written, including the lazy singleton each carried. Reads
+  `S3_ENDPOINT` / `S3_REGION` / `S3_BUCKET` / `S3_ACCESS_KEY_ID` /
+  `S3_SECRET_ACCESS_KEY`, falls back to a local adapter on `MEDIA_ROOT`, and
+  otherwise throws naming what is missing — a media surface that silently
+  no-ops is worse than a boot failure. Memoized per resolved config, so
+  per-request calls reuse one client and its signed-URL cache. Takes any
+  `Record<string, string | undefined>`, so no `$env` import enters the package.
+- **`cachedImage(adapter, key, produce, options?)`** and
+  **`store.cached(...)`** — bucket-as-cache in front of a remote image source.
+  Stored copy first (the producer is never called on a hit), one producer call
+  per stampede, immutable headers, `onStoreError` for the write that would
+  otherwise silently make you pay twice. Extracted from yoga's Google Places
+  hero proxy, which had grown all of it inline.
+- **`fetchImage(url, options?)`** — GET an image from a remote URL, rejecting
+  failed and non-image responses (an error page's HTML must never land in the
+  cache as a photo), transcoded to WebP by default.
+- **`toWebp(bytes, quality?)`** — the transcode on its own; returns the input
+  untouched when sharp cannot read it, because an optimisation must never lose
+  an image you already hold.
+- **`store.resolveUrl(key, size?, expiresIn?)`** + `basePath` on
+  `MediaStoreConfig` — presigned when the adapter can sign, else
+  `basePath/<variant key>` for the same-origin route. thebest had this fallback
+  written by hand across two modules.
+- **`DeriveSource` gains `prefix` and `entityId`** (additive), so a `derive`
+  hook and its `onDeriveError` can name the entity they failed on. yoga was
+  closing over the id to log it.
+
+### Fixed
+- **`getStorageKey` rejects filenames containing `/`, `\\` or `..`.** Filenames
+  are generated, but they round-trip through DB rows and form fields before
+  coming back to be deleted — thebest's delete action passes one straight from
+  `formData`, so a crafted value reached outside the entity's own folder.
+  `serveMedia` already guarded the read path; this is the write/delete one.
+
+### Changed
+- `ImageBytes.body` is `Uint8Array<ArrayBuffer>` — the concrete view `Response`
+  and `Blob` accept.
+- README caught up with 0.5.0: `get()` on the adapter interface, `serveMedia`,
+  `createMediaStore`, `getSignedUrl`.
+
+### Adopted by the apps
+- yoga: `photo-storage.ts` is now bucket names + Polish copy + the placeholder
+  hook (−40 lines); `/api/photo` keeps the Google policy (budget guard, ref
+  self-heal, negative caches) and nothing else (−60 lines, no more sharp, no
+  more hand-rolled in-flight map).
+- thebest: `media.ts` + `image-urls.ts` lost the adapter singleton, the
+  presign-or-fallback branch and the split-brain addressing; the tour upload
+  action no longer re-states the 15 MB limit it shares with `MEDIA_CONFIG`.
+
 ## 0.5.0 — 2026-08-09
 
 ### Added

package/README.md

@@ -34,25 +34,37 @@ the seam.
 
 ## Quick Start
 
+Bind the pipeline once per app, then call it from anywhere:
+
 ```ts
-import { createS3Adapter, processAndStore, getMediaUrl } from '@nomideusz/svelte-media/server';
-
-const storage = createS3Adapter({
-  endpoint:        process.env.S3_ENDPOINT!,     // https://xxx.r2.cloudflarestorage.com
-  region:          'auto',                        // 'auto' for R2, 'us-east-1' for AWS
-  bucket:          process.env.S3_BUCKET!,
-  accessKeyId:     process.env.S3_KEY!,
-  secretAccessKey: process.env.S3_SECRET!,
-  publicUrl:       process.env.S3_PUBLIC_URL!,   // https://pub-xxx.r2.dev
-  forcePathStyle:  true,                          // true for MinIO/R2, false for Railway/AWS
-});
+// lib/server/media.ts
+import { adapterFromEnv, createMediaStore } from '@nomideusz/svelte-media/server';
+
+export const media = () =>
+  createMediaStore({
+    adapter: adapterFromEnv(process.env, { forcePathStyle: false }),
+    basePath: '/api/images',          // your same-origin serving route
+    maxFileSize: 15 * 1024 * 1024,
+  });
+```
 
-const stored = await processAndStore(storage, file, 'tours', tourId);
+`adapterFromEnv` reads `S3_ENDPOINT` / `S3_REGION` / `S3_BUCKET` /
+`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY`, falls back to local files when only
+`MEDIA_ROOT` is set, and throws naming what is missing otherwise. It memoizes
+per config, so calling it every request reuses one client (and its signed-URL
+cache). Pass any `{ [key]: string | undefined }` — SvelteKit's
+`$env/dynamic/private` works as-is.
+
+```ts
+const stored = await media().store(file, 'tours', tourId);
 // { filename, originalName, prefix, entityId, sizes: { original, thumbnail, medium, large } }
 
-const src = getMediaUrl(storage, stored.prefix, stored.entityId, stored.filename, 'medium');
+const src = await media().resolveUrl(stored.sizes.original, 'medium');
 ```
 
+Prefer the lower-level `createS3Adapter` / `processAndStore` when you want the
+adapter built from something other than env vars.
+
 Store `stored` on your row — the helpers below all take
 `(prefix, entityId, filename)`, so keep those three. Nothing in the package
 touches a database.
@@ -103,25 +115,32 @@ is exported as `IMAGE_SIZES`.
 
 ## Storage adapters
 
-The seam is three methods:
+The seam is four methods:
 
 ```ts
 interface StorageAdapter {
   put(key: string, buffer: Buffer, contentType: string): Promise<void>;
+  get(key: string): Promise<StorageObject | null>;   // null = missing; rejects on real failures
   delete(key: string): Promise<void>;
-  getUrl(key: string): string;
+  getUrl(key: string): string;                       // throws without a publicUrl
 }
 ```
 
-Two ship with the package:
+Two ship with the package, plus the env-driven picker:
 
 ```ts
-import { createS3Adapter, createLocalAdapter } from '@nomideusz/svelte-media/server';
+import {
+  adapterFromEnv, createS3Adapter, createLocalAdapter,
+} from '@nomideusz/svelte-media/server';
 
-createS3Adapter({ /* S3Config, above */ });   // R2, MinIO, Tigris, AWS
+adapterFromEnv(process.env, { bucket: 'photos', region: 'garage' }); // S3, else MEDIA_ROOT
+createS3Adapter({ /* S3Config, above */ });   // R2, MinIO, Garage, Tigris, AWS
 createLocalAdapter({ root: '/data/images' }); // writes under root, mkdir -p
 ```
 
+`createS3Adapter` also returns `getSignedUrl(key, expiresIn?)` for private
+buckets, with expiry-buffered caching and in-flight dedupe.
+
 Anything satisfying the interface works — write your own for a CDN or a test
 double.
 
@@ -152,6 +171,44 @@ import { deleteMedia } from '@nomideusz/svelte-media/server';
 await deleteMedia(storage, stored.prefix, stored.entityId, stored.filename);
 ```
 
+## Serving
+
+A same-origin route is the whole of `serveMedia` — key validation (including
+`..` traversal), 404 on missing, immutable cache headers:
+
+```ts
+// routes/photos/[...key]/+server.ts
+export const GET = ({ params }) => media().serve(params.key);
+```
+
+`store.resolveUrl(key, size?)` picks the right URL for whichever storage you
+ended up with: a presigned URL when the adapter can sign, else
+`basePath/<variant key>` pointing at that route.
+
+## Caching remote images
+
+For images that come from somewhere else — a billed photo API, a partner CDN —
+`cached()` turns your bucket into the cache in front of it:
+
+```ts
+import { fetchImage } from '@nomideusz/svelte-media/server';
+
+const res = await media().cached(
+  `schools/${id}/hero.webp`,
+  () => fetchImage(`https://api.example/photo/${ref}`),   // only on a miss
+  { onStoreError: (e, key) => log.error(`write failed for ${key}`, e) },
+);
+if (!res) error(404, 'No photo');
+return res;
+```
+
+A stored copy is streamed without calling the producer at all; concurrent misses
+for one key share a single producer call, so a CDN stampede buys one copy rather
+than one per PoP. `fetchImage` rejects non-image and failed responses (an error
+page's HTML must never land in the cache as a photo) and transcodes to WebP —
+`toWebp` on its own does that half, returning the input untouched if sharp
+cannot read it.
+
 ## Components
 
 > **Demo-grade.** Both production apps built on this package hand-roll their
@@ -195,10 +252,18 @@ the same reason: it renders on the client, where the adapter cannot go.
 
 ```ts
 // ── @nomideusz/svelte-media/server ──
-createS3Adapter(config: S3Config): StorageAdapter
+adapterFromEnv(env, options?): StorageAdapter            // S3_* / MEDIA_ROOT, memoized
+createS3Adapter(config: S3Config): S3Adapter
 createLocalAdapter(config: LocalConfig): StorageAdapter
+createMediaStore({ adapter, basePath?, ...limits, derive? }): MediaStore
+  // .store .remove .get .serve .url .signedUrl .resolveUrl .cached .validate
 processAndStore(adapter, file, prefix, entityId, config?): Promise<StoredMedia>
 deleteMedia(adapter, prefix, entityId, filename): Promise<void>
+deleteMediaByKey(adapter, key): Promise<void>            // joined original key
+serveMedia(adapter, key): Promise<Response>
+cachedImage(adapter, key, produce, options?): Promise<Response | null>
+fetchImage(url, options?): Promise<ImageBytes | null>
+toWebp(bytes, quality = 80): Promise<ImageBytes>
 getMediaUrl(adapter, prefix, entityId, filename, size = 'medium'): string
 
 // ── @nomideusz/svelte-media (client-safe) ──
@@ -211,8 +276,10 @@ ImageUpload, ImageGallery
 
 Key helpers are exported from both entries, so server code needs only one import.
 
-Types: `StorageAdapter`, `S3Config`, `LocalConfig`, `StoredMedia`, `ImageSize`,
-`MediaConfig`, `ValidationResult`.
+Types: `StorageAdapter`, `S3Adapter`, `StorageObject`, `S3Config`,
+`LocalConfig`, `MediaStore`, `MediaStoreConfig`, `StoredMedia`, `ImageSize`,
+`MediaConfig`, `ValidationResult`, `ValidationErrorCode`, `DeriveSource`,
+`ImageBytes`, `EnvAdapterOptions`.
 
 ## Development
 

package/dist/core/env.d.ts

@@ -0,0 +1,23 @@
+import type { StorageAdapter } from './types.js';
+/** Anything with string values — `process.env`, or SvelteKit's `$env/dynamic/private`. */
+export type EnvSource = Record<string, string | undefined>;
+export interface EnvAdapterOptions {
+    /** Fallback when `S3_BUCKET` is unset. */
+    bucket?: string;
+    /** Fallback when `S3_REGION` is unset. Default `'auto'`. */
+    region?: string;
+    /** Base public URL for `getUrl()` — omit for private buckets. */
+    publicUrl?: string;
+    /** Default true (MinIO/Garage/R2); false for Railway/AWS virtual-hosted. */
+    forcePathStyle?: boolean;
+}
+/**
+ * The storage adapter this deployment is configured for:
+ *
+ *   - S3 when `S3_ENDPOINT` + `S3_ACCESS_KEY_ID` + `S3_SECRET_ACCESS_KEY` and a
+ *     bucket (`S3_BUCKET` or `options.bucket`) are all present
+ *   - local files when `MEDIA_ROOT` is set (dev machines, no bucket)
+ *   - otherwise it throws, naming what is missing — a media surface that
+ *     silently no-ops is worse than a boot failure.
+ */
+export declare function adapterFromEnv(env: EnvSource, options?: EnvAdapterOptions): StorageAdapter;

package/dist/core/env.js

@@ -0,0 +1,59 @@
+// Storage wiring from environment variables — server-only.
+//
+// Both source apps had hand-written this: read S3_*, build one lazy adapter,
+// fall back (or throw) when the vars are absent. They drifted — one defaulted
+// to path-style addressing for uploads while signing reads virtual-hosted, and
+// each carried its own singleton. The env NAMES are the shared part; the
+// defaults that differ per deployment (bucket, region, addressing) stay
+// arguments.
+import { createS3Adapter } from './adapter.js';
+import { createLocalAdapter } from './local-adapter.js';
+// One adapter per distinct config, so repeated calls (every request) reuse the
+// S3 client and its signed-URL cache. Keyed by the resolved config, so a
+// changed env var in dev builds a new one instead of serving a stale client.
+const adapters = new Map();
+/**
+ * The storage adapter this deployment is configured for:
+ *
+ *   - S3 when `S3_ENDPOINT` + `S3_ACCESS_KEY_ID` + `S3_SECRET_ACCESS_KEY` and a
+ *     bucket (`S3_BUCKET` or `options.bucket`) are all present
+ *   - local files when `MEDIA_ROOT` is set (dev machines, no bucket)
+ *   - otherwise it throws, naming what is missing — a media surface that
+ *     silently no-ops is worse than a boot failure.
+ */
+export function adapterFromEnv(env, options = {}) {
+    const endpoint = env.S3_ENDPOINT;
+    const accessKeyId = env.S3_ACCESS_KEY_ID;
+    const secretAccessKey = env.S3_SECRET_ACCESS_KEY;
+    const bucket = env.S3_BUCKET ?? options.bucket;
+    if (endpoint && accessKeyId && secretAccessKey && bucket) {
+        const config = {
+            endpoint,
+            region: env.S3_REGION ?? options.region ?? 'auto',
+            bucket,
+            accessKeyId,
+            secretAccessKey,
+            publicUrl: options.publicUrl,
+            forcePathStyle: options.forcePathStyle,
+        };
+        return memo(`s3:${JSON.stringify(config)}`, () => createS3Adapter(config));
+    }
+    const root = env.MEDIA_ROOT;
+    if (root)
+        return memo(`local:${root}`, () => createLocalAdapter({ root }));
+    const missing = [
+        !endpoint && 'S3_ENDPOINT',
+        !accessKeyId && 'S3_ACCESS_KEY_ID',
+        !secretAccessKey && 'S3_SECRET_ACCESS_KEY',
+        !bucket && 'S3_BUCKET',
+    ].filter(Boolean);
+    throw new Error(`svelte-media: no storage configured — missing ${missing.join(', ')} (or set MEDIA_ROOT for local files)`);
+}
+function memo(key, build) {
+    let adapter = adapters.get(key);
+    if (!adapter) {
+        adapter = build();
+        adapters.set(key, adapter);
+    }
+    return adapter;
+}

package/dist/core/media.js

@@ -58,6 +58,13 @@ export function generateMediaKey() {
     return `${createId()}.webp`;
 }
 export function getStorageKey(prefix, entityId, filename, size) {
+    // Filenames are generated (`<cuid2>.webp`), but they round-trip through rows
+    // and form fields before they come back here to be deleted — a `..` segment
+    // would reach outside the entity's own folder. serveMedia guards the read
+    // path; this is the write/delete one.
+    if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
+        throw new Error(`Invalid media filename: ${filename}`);
+    }
     const sizePrefix = SIZE_PREFIXES[size];
     return `${prefix}/${entityId}/${sizePrefix}${filename}`;
 }

package/dist/core/process.js

@@ -34,7 +34,7 @@ export async function processAndStore(adapter, file, prefix, entityId, config) {
     // make the caller retry a completed upload.
     let derived;
     if (config?.derive) {
-        const source = { buffer, filename, mimeType: file.type };
+        const source = { buffer, filename, mimeType: file.type, prefix, entityId };
         try {
             derived = await config.derive(source);
         }

package/dist/core/remote.d.ts

@@ -0,0 +1,42 @@
+import type { StorageAdapter } from './types.js';
+export interface ImageBytes {
+    /** Concrete ArrayBuffer view — `Response` and `Blob` reject the SharedArrayBuffer-wide type. */
+    body: Uint8Array<ArrayBuffer>;
+    contentType: string;
+}
+/**
+ * Re-encode to WebP (~30-50% smaller than the JPEG most photo APIs serve).
+ * Returns the input untouched when sharp cannot read it — a transcode is an
+ * optimisation, never a reason to lose an image we already hold.
+ */
+export declare function toWebp(bytes: Uint8Array<ArrayBuffer>, quality?: number): Promise<ImageBytes>;
+export interface FetchImageOptions extends RequestInit {
+    /** WebP quality, or `false` to keep the upstream encoding. Default 80. */
+    webp?: number | false;
+}
+/**
+ * GET an image from a remote URL, transcoded to WebP by default.
+ * `null` when the response fails or isn't an image — an error page's HTML must
+ * never reach the cache as if it were a photo.
+ */
+export declare function fetchImage(url: string, options?: FetchImageOptions): Promise<ImageBytes | null>;
+export interface CachedImageOptions {
+    /**
+     * Called when the fetched bytes could not be stored. The response still goes
+     * out; the next request will produce them again (i.e. pay again), so wire
+     * this to your logger.
+     */
+    onStoreError?(error: unknown, key: string): void;
+}
+/**
+ * Serve `key` from storage, producing it once on the first miss.
+ *
+ * Cheapest path first: a stored copy is streamed without calling `produce` at
+ * all. Concurrent misses for the same key share one `produce` call — a CDN
+ * stampede across PoPs, or a crawler, otherwise buys one copy each.
+ *
+ * `null` means `produce` had nothing (the caller decides: 404, placeholder,
+ * fall through). A storage read that throws is treated as a miss: an
+ * unreachable bucket must not blank an image it could still fetch.
+ */
+export declare function cachedImage(adapter: StorageAdapter, key: string, produce: () => Promise<ImageBytes | null>, options?: CachedImageOptions): Promise<Response | null>;

package/dist/core/remote.js

@@ -0,0 +1,105 @@
+// Caching images that come from somewhere else — a paid photo API, a partner
+// CDN, a scraper. Server-only (sharp).
+//
+// Extracted from yoga's Google Places hero proxy, which was paying Google per
+// origin miss until it grew a bucket cache, a stampede lock and a transcode
+// step around it. All three are storage plumbing, not Places knowledge: what
+// stays in the app is which URL to call, what it costs and when to give up.
+import sharp from 'sharp';
+// Cached objects are keyed by content and never rewritten in place, so the
+// bytes behind a URL never change — same header serveMedia sends.
+const IMMUTABLE = 'public, max-age=31536000, immutable';
+/**
+ * Re-encode to WebP (~30-50% smaller than the JPEG most photo APIs serve).
+ * Returns the input untouched when sharp cannot read it — a transcode is an
+ * optimisation, never a reason to lose an image we already hold.
+ */
+export async function toWebp(bytes, quality = 80) {
+    try {
+        const webp = await sharp(Buffer.from(bytes)).webp({ quality }).toBuffer();
+        return { body: new Uint8Array(webp), contentType: 'image/webp' };
+    }
+    catch {
+        return { body: bytes, contentType: 'application/octet-stream' };
+    }
+}
+/**
+ * GET an image from a remote URL, transcoded to WebP by default.
+ * `null` when the response fails or isn't an image — an error page's HTML must
+ * never reach the cache as if it were a photo.
+ */
+export async function fetchImage(url, options = {}) {
+    const { webp = 80, ...init } = options;
+    const res = await fetch(url, { redirect: 'follow', ...init });
+    if (!res.ok)
+        return null;
+    const contentType = res.headers.get('content-type') ?? '';
+    if (!contentType.startsWith('image/'))
+        return null;
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (webp === false)
+        return { body: bytes, contentType };
+    const encoded = await toWebp(bytes, webp);
+    // sharp failed — keep the upstream type rather than toWebp's octet-stream.
+    return encoded.contentType === 'image/webp' ? encoded : { body: bytes, contentType };
+}
+// Per-adapter, so two stores in one process cannot collide on a shared key.
+const inflight = new WeakMap();
+/**
+ * Serve `key` from storage, producing it once on the first miss.
+ *
+ * Cheapest path first: a stored copy is streamed without calling `produce` at
+ * all. Concurrent misses for the same key share one `produce` call — a CDN
+ * stampede across PoPs, or a crawler, otherwise buys one copy each.
+ *
+ * `null` means `produce` had nothing (the caller decides: 404, placeholder,
+ * fall through). A storage read that throws is treated as a miss: an
+ * unreachable bucket must not blank an image it could still fetch.
+ */
+export async function cachedImage(adapter, key, produce, options = {}) {
+    const stored = await adapter.get(key).catch(() => null);
+    if (stored) {
+        return new Response(stored.body, {
+            headers: {
+                'Content-Type': stored.contentType,
+                ...(stored.contentLength != null
+                    ? { 'Content-Length': String(stored.contentLength) }
+                    : {}),
+                'Cache-Control': IMMUTABLE,
+            },
+        });
+    }
+    let pending = inflight.get(adapter);
+    if (!pending) {
+        pending = new Map();
+        inflight.set(adapter, pending);
+    }
+    let work = pending.get(key);
+    if (!work) {
+        work = (async () => {
+            const image = await produce();
+            if (!image)
+                return null;
+            // Awaited: a silent write failure means paying for these bytes again on
+            // the next request, which is the whole point of the cache.
+            try {
+                await adapter.put(key, Buffer.from(image.body), image.contentType);
+            }
+            catch (error) {
+                options.onStoreError?.(error, key);
+            }
+            return image;
+        })().finally(() => pending.delete(key));
+        pending.set(key, work);
+    }
+    const image = await work;
+    if (!image)
+        return null;
+    return new Response(image.body, {
+        headers: {
+            'Content-Type': image.contentType,
+            'Content-Length': String(image.body.byteLength),
+            'Cache-Control': IMMUTABLE,
+        },
+    });
+}

package/dist/core/store.d.ts

@@ -1,6 +1,13 @@
 import type { ImageSize, MediaConfig, StorageAdapter, StorageObject, StoredMedia, ValidationResult } from './types.js';
+import { type CachedImageOptions, type ImageBytes } from './remote.js';
 export interface MediaStoreConfig<TDerived = never> extends MediaConfig<TDerived> {
     adapter: StorageAdapter;
+    /**
+     * Where the same-origin serving route lives, e.g. `'/photos'` or
+     * `'/api/images'` — what `resolveUrl` falls back to when the adapter cannot
+     * presign (local dev, public buckets).
+     */
+    basePath?: string;
 }
 /**
  * The per-app binding — adapter, limits and derive hook bound once, so call
@@ -24,6 +31,17 @@ export interface MediaStore<TDerived = never> {
     url(key: string, size?: ImageSize): string;
     /** Presigned URL for a size variant — rejects unless the adapter is S3. */
     signedUrl(key: string, size?: ImageSize, expiresIn?: number): Promise<string>;
+    /**
+     * The URL to hand a browser: presigned when the adapter can sign (a private
+     * bucket in production), else `basePath/key` for the same-origin route.
+     * Both apps had written that fallback by hand.
+     */
+    resolveUrl(key: string, size?: ImageSize, expiresIn?: number): Promise<string>;
+    /**
+     * `cachedImage` with the bound adapter — serve a key from storage, buying it
+     * from `produce` once on the first miss.
+     */
+    cached(key: string, produce: () => Promise<ImageBytes | null>, options?: CachedImageOptions): Promise<Response | null>;
     /** `validateImageFile` with the bound limits. */
     validate(file: File): ValidationResult;
 }

package/dist/core/store.js

@@ -1,8 +1,10 @@
 import { validateImageFile, variantKey } from './media.js';
 import { processAndStore, deleteMediaByKey } from './process.js';
 import { serveMedia } from './serve.js';
+import { cachedImage } from './remote.js';
 export function createMediaStore(config) {
-    const { adapter, ...media } = config;
+    const { adapter, basePath, ...media } = config;
+    const signer = adapter.getSignedUrl?.bind(adapter);
     return {
         adapter,
         store: (file, prefix, entityId) => processAndStore(adapter, file, prefix, entityId, media),
@@ -11,12 +13,21 @@ export function createMediaStore(config) {
         serve: (key) => serveMedia(adapter, key),
         url: (key, size = 'original') => adapter.getUrl(variantKey(key, size)),
         signedUrl: (key, size = 'original', expiresIn) => {
-            const s3 = adapter;
-            if (!s3.getSignedUrl) {
+            if (!signer) {
                 return Promise.reject(new Error('signedUrl needs an S3 adapter (getSignedUrl)'));
             }
-            return s3.getSignedUrl(variantKey(key, size), expiresIn);
+            return signer(variantKey(key, size), expiresIn);
         },
+        resolveUrl: async (key, size = 'original', expiresIn) => {
+            const variant = variantKey(key, size);
+            if (signer)
+                return signer(variant, expiresIn);
+            if (!basePath) {
+                throw new Error('resolveUrl needs an S3 adapter or a basePath for the serving route');
+            }
+            return `${basePath.replace(/\/$/, '')}/${variant}`;
+        },
+        cached: (key, produce, options) => cachedImage(adapter, key, produce, options),
         validate: (file) => validateImageFile(file, media),
     };
 }

package/dist/core/types.d.ts

@@ -75,6 +75,10 @@ export interface DeriveSource {
     filename: string;
     /** The uploaded file's MIME type. */
     mimeType: string;
+    /** Storage prefix this upload went to, e.g. 'schools'. */
+    prefix: string;
+    /** The owning entity — what a failing hook needs to name in a log line. */
+    entityId: string;
 }
 /** The validation half of MediaConfig — all `validateImageFile` needs. */
 export interface ValidationConfig {

package/dist/server/index.d.ts

@@ -1,6 +1,10 @@
 export type { LocalConfig } from '../core/local-adapter.js';
 export { createS3Adapter } from '../core/adapter.js';
 export { createLocalAdapter } from '../core/local-adapter.js';
+export { adapterFromEnv } from '../core/env.js';
+export type { EnvAdapterOptions, EnvSource } from '../core/env.js';
+export { cachedImage, fetchImage, toWebp } from '../core/remote.js';
+export type { CachedImageOptions, FetchImageOptions, ImageBytes } from '../core/remote.js';
 export { processAndStore, deleteMedia, deleteMediaByKey, getMediaUrl } from '../core/process.js';
 export { serveMedia } from '../core/serve.js';
 export { createMediaStore } from '../core/store.js';

package/dist/server/index.js

@@ -1,6 +1,8 @@
 // Server-only entry: sharp, node:fs and Buffer live behind here.
 export { createS3Adapter } from '../core/adapter.js';
 export { createLocalAdapter } from '../core/local-adapter.js';
+export { adapterFromEnv } from '../core/env.js';
+export { cachedImage, fetchImage, toWebp } from '../core/remote.js';
 export { processAndStore, deleteMedia, deleteMediaByKey, getMediaUrl } from '../core/process.js';
 export { serveMedia } from '../core/serve.js';
 export { createMediaStore } from '../core/store.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomideusz/svelte-media",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Image upload, processing, and S3-compatible storage for Svelte 5 apps.",
   "type": "module",
   "sideEffects": false,
@@ -47,15 +47,15 @@
   },
   "devDependencies": {
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.69.1",
+    "@sveltejs/kit": "^2.70.2",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@types/node": "^25.9.4",
-    "svelte": "^5.56.4",
+    "svelte": "^5.56.9",
     "svelte-check": "^4.7.1",
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "keywords": [
     "svelte",