@ayepi/files 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @ayepi/files
+
+A generic, **S3-like**, key-based file store for ayepi: stream bytes in under a key,
+stream them back out, list by prefix, and hand out **presigned** upload/download URLs that
+expire. The interface is tiny and storage-agnostic; the bundled filesystem store
+(`@ayepi/files/fs`) is the default, and `@ayepi/aws`'s `s3Files` implements the same
+`FileStore`. Everything is **stream-first** — `put` takes a `ReadableStream`, `get` returns
+an object you read as a stream.
+
+```sh
+pnpm add @ayepi/files @ayepi/core
+```
+
+The `.` entry is dependency-light (just types + stream helpers); `./fs` and `./server` are
+Node-only.
+
+```ts
+import { fsFiles } from '@ayepi/files/fs'
+import { mountFiles } from '@ayepi/files/server'
+
+const files = fsFiles({ dir: './uploads' })
+await files.put('reports/2026.csv', someStream, { contentType: 'text/csv' })
+const obj = await files.get('reports/2026.csv')
+for (const f of (await files.list('reports/')).files) console.log(f.key, f.size)
+
+// presigned URLs for a store that can't self-serve (the filesystem one):
+const { presign } = mountFiles(app, files, { secret: process.env.FILES_SECRET! })
+const url = await presign.presignDownload('reports/2026.csv', { expiresIn: 60 })
+```
+
+## How it works
+
+- **One small interface.** `FileStore` is `put` / `get` / `head` / `delete` / `list` —
+  S3's core shape, nothing more. `fsFiles` and `@ayepi/aws`'s `s3Files` both implement it,
+  so code written against `FileStore` is portable across backends.
+- **Stream-first.** `put` accepts any `FileBody` (a `ReadableStream`, `Uint8Array`, `Blob`,
+  or `string`); `get` returns a `FileObject` you read as a stream (or fully via
+  `bytes()`/`text()`). The `transfer` helper pipes one store into another without buffering.
+- **Filesystem default.** `fsFiles({ dir })` stores each object as a file (the key is its
+  relative `/`-path) with `contentType`/`metadata` in a `.ayepi-meta` sidecar. Writes go to
+  a temp file and are atomically `rename`d into place; reads stream straight off disk.
+- **Presigned URLs for stores that can't self-serve.** S3 signs its own URLs. The
+  filesystem store has no HTTP surface, so `@ayepi/files/server` (`mountFiles` /
+  `createFilesHandler`) signs short-lived HMAC tokens and serves the matching GET/PUT.
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-files.md`](./ayepi-files.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/files) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/fs.cjs

@@ -0,0 +1,168 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_index = require("./index.cjs");
+let node_fs_promises = require("node:fs/promises");
+let node_fs = require("node:fs");
+let node_stream = require("node:stream");
+let node_stream_promises = require("node:stream/promises");
+let node_path = require("node:path");
+let node_crypto = require("node:crypto");
+//#region src/fs.ts
+/**
+* # @ayepi/files/fs
+*
+* The default filesystem-backed {@link FileStore}: objects live as files under a root
+* directory (the key is the relative path, `/`-separated), with `contentType`/`metadata`
+* kept in a small sidecar next to each object. Writes are **streamed** to a temp file and
+* atomically `rename`d into place; reads stream straight off disk. For presigned URLs (the
+* filesystem can't self-serve), wire it with `@ayepi/files/server`.
+*
+* @module
+*/
+/** Sidecar suffix holding an object's `contentType`/`metadata`. Keys ending in it are reserved. */
+const META_SUFFIX = ".ayepi-meta";
+/** Default page size for {@link FileStore.list}. */
+const DEFAULT_LIST_LIMIT = 1e3;
+/** Map a `/`-separated key to an absolute path, rejecting traversal / empty segments. */
+function keyToPath(dir, key) {
+	const parts = key.split("/");
+	if (key === "" || parts.some((p) => p === "" || p === "." || p === "..")) throw new Error(`@ayepi/files: invalid key "${key}"`);
+	return (0, node_path.join)(dir, ...parts);
+}
+/** Whether a file path is a metadata sidecar (excluded from listings). */
+const isSidecar = (path) => path.endsWith(META_SUFFIX);
+/**
+* Create a filesystem-backed {@link FileStore} rooted at `opts.dir`.
+*
+* @example
+* ```ts
+* const files = fsFiles({ dir: './uploads' });
+* await files.put('a/b.txt', 'hello', { contentType: 'text/plain' });
+* ```
+*/
+function fsFiles(opts) {
+	const root = opts.dir;
+	const report = (err, op, key) => {
+		try {
+			opts.onError?.(err, op, key);
+		} catch {}
+	};
+	/** Run an op so a real I/O failure is reported (then re-thrown); ENOENT is left to the caller. */
+	const guard = async (op, key, fn) => {
+		try {
+			return await fn();
+		} catch (err) {
+			report(err, op, key);
+			throw err;
+		}
+	};
+	const isNotFound = (err) => err?.code === "ENOENT";
+	const readMeta = async (path) => {
+		try {
+			return JSON.parse(await (0, node_fs_promises.readFile)(path + META_SUFFIX, "utf8"));
+		} catch {
+			return {};
+		}
+	};
+	const infoFor = async (key, path) => {
+		const s = await (0, node_fs_promises.stat)(path);
+		const meta = await readMeta(path);
+		return {
+			key,
+			size: s.size,
+			modifiedAt: Math.round(s.mtimeMs),
+			etag: `"${s.size}-${Math.round(s.mtimeMs)}"`,
+			contentType: meta.contentType,
+			metadata: meta.metadata
+		};
+	};
+	return {
+		async put(key, body, options) {
+			const path = keyToPath(root, key);
+			return guard("put", key, async () => {
+				await (0, node_fs_promises.mkdir)((0, node_path.dirname)(path), { recursive: true });
+				const tmp = `${path}.${(0, node_crypto.randomBytes)(8).toString("hex")}.tmp`;
+				await (0, node_stream_promises.pipeline)(node_stream.Readable.fromWeb(normalize(body)), (0, node_fs.createWriteStream)(tmp));
+				await (0, node_fs_promises.rename)(tmp, path);
+				const meta = {
+					contentType: options?.contentType,
+					metadata: options?.metadata ? { ...options.metadata } : void 0
+				};
+				if (meta.contentType !== void 0 || meta.metadata !== void 0) await (0, node_fs_promises.writeFile)(path + META_SUFFIX, JSON.stringify(meta));
+				return infoFor(key, path);
+			});
+		},
+		async head(key) {
+			const path = keyToPath(root, key);
+			try {
+				return await infoFor(key, path);
+			} catch (err) {
+				if (isNotFound(err)) return;
+				report(err, "head", key);
+				throw err;
+			}
+		},
+		async get(key) {
+			const path = keyToPath(root, key);
+			let info;
+			try {
+				info = await infoFor(key, path);
+			} catch (err) {
+				if (isNotFound(err)) return;
+				report(err, "get", key);
+				throw err;
+			}
+			const open = () => node_stream.Readable.toWeb((0, node_fs.createReadStream)(path));
+			return {
+				info,
+				stream: open,
+				bytes: () => require_index.collect(open()),
+				text: async () => new TextDecoder().decode(await require_index.collect(open()))
+			};
+		},
+		async delete(key) {
+			const path = keyToPath(root, key);
+			return guard("delete", key, async () => {
+				try {
+					await (0, node_fs_promises.unlink)(path);
+				} catch (err) {
+					if (isNotFound(err)) return false;
+					throw err;
+				}
+				await (0, node_fs_promises.unlink)(path + META_SUFFIX).catch(() => {});
+				return true;
+			});
+		},
+		async list(prefix, options) {
+			const limit = options?.limit ?? DEFAULT_LIST_LIMIT;
+			return guard("list", prefix, async () => {
+				const keys = [];
+				const safeReaddir = async (abs) => {
+					try {
+						return await (0, node_fs_promises.readdir)(abs, { withFileTypes: true });
+					} catch (err) {
+						if (isNotFound(err)) return [];
+						throw err;
+					}
+				};
+				const walk = async (abs) => {
+					for (const e of await safeReaddir(abs)) {
+						const child = (0, node_path.join)(abs, e.name);
+						if (e.isDirectory()) await walk(child);
+						else if (!isSidecar(child)) keys.push((0, node_path.relative)(root, child).split(node_path.sep).join("/"));
+					}
+				};
+				await walk(root);
+				const matched = keys.filter((k) => k.startsWith(prefix) && (options?.cursor === void 0 || k > options.cursor)).sort();
+				const page = matched.slice(0, limit);
+				return {
+					files: await Promise.all(page.map((k) => infoFor(k, keyToPath(root, k)))),
+					cursor: matched.length > limit ? page[page.length - 1] : void 0
+				};
+			});
+		}
+	};
+}
+/** Local alias so `put` can normalize its body without re-importing under a shadowed name. */
+const normalize = (body) => require_index.toStream(body);
+//#endregion
+exports.fsFiles = fsFiles;

package/dist/fs.d.cts

@@ -0,0 +1,23 @@
+import { FileStore } from "./index.cjs";
+
+//#region src/fs.d.ts
+
+/** Options for {@link fsFiles}. */
+interface FsFilesOptions {
+  /** Root directory objects are stored under (created on demand). */
+  readonly dir: string;
+  /** Observe an I/O error (it's also re-thrown to the caller). Off by default; must not throw. */
+  readonly onError?: (err: unknown, op: string, key: string) => void;
+}
+/**
+ * Create a filesystem-backed {@link FileStore} rooted at `opts.dir`.
+ *
+ * @example
+ * ```ts
+ * const files = fsFiles({ dir: './uploads' });
+ * await files.put('a/b.txt', 'hello', { contentType: 'text/plain' });
+ * ```
+ */
+declare function fsFiles(opts: FsFilesOptions): FileStore;
+//#endregion
+export { FsFilesOptions, fsFiles };

package/dist/fs.d.ts

@@ -0,0 +1,23 @@
+import { FileStore } from "./index.js";
+
+//#region src/fs.d.ts
+
+/** Options for {@link fsFiles}. */
+interface FsFilesOptions {
+  /** Root directory objects are stored under (created on demand). */
+  readonly dir: string;
+  /** Observe an I/O error (it's also re-thrown to the caller). Off by default; must not throw. */
+  readonly onError?: (err: unknown, op: string, key: string) => void;
+}
+/**
+ * Create a filesystem-backed {@link FileStore} rooted at `opts.dir`.
+ *
+ * @example
+ * ```ts
+ * const files = fsFiles({ dir: './uploads' });
+ * await files.put('a/b.txt', 'hello', { contentType: 'text/plain' });
+ * ```
+ */
+declare function fsFiles(opts: FsFilesOptions): FileStore;
+//#endregion
+export { FsFilesOptions, fsFiles };

package/dist/fs.js

@@ -0,0 +1,167 @@
+import { collect, toStream } from "./index.js";
+import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { createReadStream, createWriteStream } from "node:fs";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { randomBytes } from "node:crypto";
+//#region src/fs.ts
+/**
+* # @ayepi/files/fs
+*
+* The default filesystem-backed {@link FileStore}: objects live as files under a root
+* directory (the key is the relative path, `/`-separated), with `contentType`/`metadata`
+* kept in a small sidecar next to each object. Writes are **streamed** to a temp file and
+* atomically `rename`d into place; reads stream straight off disk. For presigned URLs (the
+* filesystem can't self-serve), wire it with `@ayepi/files/server`.
+*
+* @module
+*/
+/** Sidecar suffix holding an object's `contentType`/`metadata`. Keys ending in it are reserved. */
+const META_SUFFIX = ".ayepi-meta";
+/** Default page size for {@link FileStore.list}. */
+const DEFAULT_LIST_LIMIT = 1e3;
+/** Map a `/`-separated key to an absolute path, rejecting traversal / empty segments. */
+function keyToPath(dir, key) {
+	const parts = key.split("/");
+	if (key === "" || parts.some((p) => p === "" || p === "." || p === "..")) throw new Error(`@ayepi/files: invalid key "${key}"`);
+	return join(dir, ...parts);
+}
+/** Whether a file path is a metadata sidecar (excluded from listings). */
+const isSidecar = (path) => path.endsWith(META_SUFFIX);
+/**
+* Create a filesystem-backed {@link FileStore} rooted at `opts.dir`.
+*
+* @example
+* ```ts
+* const files = fsFiles({ dir: './uploads' });
+* await files.put('a/b.txt', 'hello', { contentType: 'text/plain' });
+* ```
+*/
+function fsFiles(opts) {
+	const root = opts.dir;
+	const report = (err, op, key) => {
+		try {
+			opts.onError?.(err, op, key);
+		} catch {}
+	};
+	/** Run an op so a real I/O failure is reported (then re-thrown); ENOENT is left to the caller. */
+	const guard = async (op, key, fn) => {
+		try {
+			return await fn();
+		} catch (err) {
+			report(err, op, key);
+			throw err;
+		}
+	};
+	const isNotFound = (err) => err?.code === "ENOENT";
+	const readMeta = async (path) => {
+		try {
+			return JSON.parse(await readFile(path + META_SUFFIX, "utf8"));
+		} catch {
+			return {};
+		}
+	};
+	const infoFor = async (key, path) => {
+		const s = await stat(path);
+		const meta = await readMeta(path);
+		return {
+			key,
+			size: s.size,
+			modifiedAt: Math.round(s.mtimeMs),
+			etag: `"${s.size}-${Math.round(s.mtimeMs)}"`,
+			contentType: meta.contentType,
+			metadata: meta.metadata
+		};
+	};
+	return {
+		async put(key, body, options) {
+			const path = keyToPath(root, key);
+			return guard("put", key, async () => {
+				await mkdir(dirname(path), { recursive: true });
+				const tmp = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+				await pipeline(Readable.fromWeb(normalize(body)), createWriteStream(tmp));
+				await rename(tmp, path);
+				const meta = {
+					contentType: options?.contentType,
+					metadata: options?.metadata ? { ...options.metadata } : void 0
+				};
+				if (meta.contentType !== void 0 || meta.metadata !== void 0) await writeFile(path + META_SUFFIX, JSON.stringify(meta));
+				return infoFor(key, path);
+			});
+		},
+		async head(key) {
+			const path = keyToPath(root, key);
+			try {
+				return await infoFor(key, path);
+			} catch (err) {
+				if (isNotFound(err)) return;
+				report(err, "head", key);
+				throw err;
+			}
+		},
+		async get(key) {
+			const path = keyToPath(root, key);
+			let info;
+			try {
+				info = await infoFor(key, path);
+			} catch (err) {
+				if (isNotFound(err)) return;
+				report(err, "get", key);
+				throw err;
+			}
+			const open = () => Readable.toWeb(createReadStream(path));
+			return {
+				info,
+				stream: open,
+				bytes: () => collect(open()),
+				text: async () => new TextDecoder().decode(await collect(open()))
+			};
+		},
+		async delete(key) {
+			const path = keyToPath(root, key);
+			return guard("delete", key, async () => {
+				try {
+					await unlink(path);
+				} catch (err) {
+					if (isNotFound(err)) return false;
+					throw err;
+				}
+				await unlink(path + META_SUFFIX).catch(() => {});
+				return true;
+			});
+		},
+		async list(prefix, options) {
+			const limit = options?.limit ?? DEFAULT_LIST_LIMIT;
+			return guard("list", prefix, async () => {
+				const keys = [];
+				const safeReaddir = async (abs) => {
+					try {
+						return await readdir(abs, { withFileTypes: true });
+					} catch (err) {
+						if (isNotFound(err)) return [];
+						throw err;
+					}
+				};
+				const walk = async (abs) => {
+					for (const e of await safeReaddir(abs)) {
+						const child = join(abs, e.name);
+						if (e.isDirectory()) await walk(child);
+						else if (!isSidecar(child)) keys.push(relative(root, child).split(sep).join("/"));
+					}
+				};
+				await walk(root);
+				const matched = keys.filter((k) => k.startsWith(prefix) && (options?.cursor === void 0 || k > options.cursor)).sort();
+				const page = matched.slice(0, limit);
+				return {
+					files: await Promise.all(page.map((k) => infoFor(k, keyToPath(root, k)))),
+					cursor: matched.length > limit ? page[page.length - 1] : void 0
+				};
+			});
+		}
+	};
+}
+/** Local alias so `put` can normalize its body without re-importing under a shadowed name. */
+const normalize = (body) => toStream(body);
+//#endregion
+export { fsFiles };

package/dist/index.cjs

@@ -0,0 +1,48 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/index.ts
+/** Normalize any {@link FileBody} into a byte stream. */
+function toStream(body) {
+	if (body instanceof ReadableStream) return body;
+	if (body instanceof Blob) return body.stream();
+	const bytes = typeof body === "string" ? new TextEncoder().encode(body) : body;
+	return new ReadableStream({ start(controller) {
+		controller.enqueue(bytes);
+		controller.close();
+	} });
+}
+/** Read a byte stream fully into a single `Uint8Array`. */
+async function collect(stream) {
+	const reader = stream.getReader();
+	const chunks = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		chunks.push(value);
+		total += value.length;
+	}
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const c of chunks) {
+		out.set(c, offset);
+		offset += c.length;
+	}
+	return out;
+}
+/**
+* Stream an object from one store to another (`src[srcKey] → dst[dstKey]`) without buffering
+* it all in memory. Carries the source's `contentType`/`metadata` unless overridden. Throws
+* if the source key is missing.
+*/
+async function transfer(src, srcKey, dst, dstKey, opts) {
+	const obj = await src.get(srcKey);
+	if (!obj) throw new Error(`transfer: source key "${srcKey}" not found`);
+	return dst.put(dstKey, obj.stream(), {
+		contentType: opts?.contentType ?? obj.info.contentType,
+		metadata: opts?.metadata ?? obj.info.metadata
+	});
+}
+//#endregion
+exports.collect = collect;
+exports.toStream = toStream;
+exports.transfer = transfer;

package/dist/index.d.cts

@@ -0,0 +1,126 @@
+//#region src/index.d.ts
+/**
+ * # @ayepi/files
+ *
+ * A generic, **S3-like** key-based file store: stream bytes in under a key, stream them
+ * back out, list by prefix, and hand out **presigned** upload/download URLs that expire.
+ * The interface is tiny and storage-agnostic; the bundled {@link fsFiles | filesystem
+ * store} (`@ayepi/files/fs`) is the default, and `@ayepi/aws`'s `s3Files` implements the
+ * same {@link FileStore}. Presigned URLs for a store that can't self-serve (the filesystem
+ * one) are wired with `@ayepi/files/server` ({@link mountFiles} / `createFilesHandler`).
+ *
+ * Everything is **stream-first** — `put` takes a `ReadableStream` (or any {@link FileBody}),
+ * `get` returns a {@link FileObject} you read as a stream — with helpers
+ * ({@link toStream}, {@link collect}, {@link transfer}) for the common piping/transfer needs.
+ *
+ * ```ts
+ * import { fsFiles } from '@ayepi/files/fs';
+ * const files = fsFiles({ dir: './uploads' });
+ * await files.put('reports/2026.csv', someReadableStream, { contentType: 'text/csv' });
+ * const obj = await files.get('reports/2026.csv');
+ * await obj?.stream().pipeTo(destination);
+ * for (const f of (await files.list('reports/')).files) console.log(f.key, f.size);
+ * ```
+ *
+ * @module
+ */
+/** Metadata about a stored object (no body) — the S3 `HeadObject` shape. */
+interface FileInfo {
+  /** The object's key. */
+  readonly key: string;
+  /** Size in bytes. */
+  readonly size: number;
+  /** MIME type, if known/stored. */
+  readonly contentType?: string;
+  /** An opaque content tag (e.g. a hash) when the backend supplies one. */
+  readonly etag?: string;
+  /** Last-modified time (ms epoch). */
+  readonly modifiedAt: number;
+  /** Arbitrary user metadata stored alongside the object. */
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+/** Anything you can hand to {@link FileStore.put} as the body — a stream is preferred. */
+type FileBody = ReadableStream<Uint8Array> | Uint8Array | Blob | string;
+/** A stored object's metadata plus lazy accessors for its bytes. */
+interface FileObject {
+  /** The object's metadata. */
+  readonly info: FileInfo;
+  /** The body as a byte stream (read it once). */
+  stream(): ReadableStream<Uint8Array>;
+  /** Read the whole body into memory. */
+  bytes(): Promise<Uint8Array>;
+  /** Read the whole body as a UTF-8 string. */
+  text(): Promise<string>;
+}
+/** Options for {@link FileStore.put}. */
+interface PutOptions {
+  /** MIME type to record (and serve). */
+  readonly contentType?: string;
+  /** Arbitrary user metadata to store. */
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+/** Options for {@link FileStore.list}. */
+interface ListOptions {
+  /** Max keys to return in this page (the backend may return fewer). */
+  readonly limit?: number;
+  /** Continuation cursor from a previous page's {@link ListResult.cursor}. */
+  readonly cursor?: string;
+}
+/** A page of {@link FileStore.list} results. */
+interface ListResult {
+  /** The objects in this page (metadata only), key-sorted. */
+  readonly files: readonly FileInfo[];
+  /** Pass to a follow-up `list({ cursor })` to continue; absent when the listing is complete. */
+  readonly cursor?: string;
+}
+/**
+ * The storage contract — a small, S3-like, key-based interface. Implementations:
+ * {@link fsFiles} (`@ayepi/files/fs`) and `s3Files` (`@ayepi/aws`).
+ */
+interface FileStore {
+  /** Store `body` under `key` (overwriting any existing object); returns the resulting metadata. */
+  put(key: string, body: FileBody, opts?: PutOptions): Promise<FileInfo>;
+  /** Fetch an object (metadata + lazy body), or `undefined` if the key doesn't exist. */
+  get(key: string): Promise<FileObject | undefined>;
+  /** Fetch just the metadata, or `undefined` if the key doesn't exist. */
+  head(key: string): Promise<FileInfo | undefined>;
+  /** Delete an object; resolves `true` if it existed. */
+  delete(key: string): Promise<boolean>;
+  /** List objects whose key starts with `prefix`, paginated. */
+  list(prefix: string, opts?: ListOptions): Promise<ListResult>;
+}
+/** Options for {@link Presigner.presignDownload}. */
+interface PresignDownloadOptions {
+  /** Seconds until the URL expires (default chosen by the presigner). */
+  readonly expiresIn?: number;
+}
+/** Options for {@link Presigner.presignUpload}. */
+interface PresignUploadOptions {
+  /** Seconds until the URL expires (default chosen by the presigner). */
+  readonly expiresIn?: number;
+  /** Pin the `Content-Type` the upload must use. */
+  readonly contentType?: string;
+}
+/**
+ * The presign capability — kept separate from {@link FileStore} because not every store can
+ * self-serve. `s3Files` implements it natively; the filesystem store gets it from
+ * `@ayepi/files/server` ({@link mountFiles}).
+ */
+interface Presigner {
+  /** A time-limited URL to GET `key`. */
+  presignDownload(key: string, opts?: PresignDownloadOptions): Promise<string>;
+  /** A time-limited URL to PUT `key`. */
+  presignUpload(key: string, opts?: PresignUploadOptions): Promise<string>;
+}
+/** Normalize any {@link FileBody} into a byte stream. */
+declare function toStream(body: FileBody): ReadableStream<Uint8Array>;
+/** Read a byte stream fully into a single `Uint8Array`. */
+declare function collect(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;
+/**
+ * Stream an object from one store to another (`src[srcKey] → dst[dstKey]`) without buffering
+ * it all in memory. Carries the source's `contentType`/`metadata` unless overridden. Throws
+ * if the source key is missing.
+ */
+declare function transfer(src: FileStore, srcKey: string, dst: FileStore, dstKey: string, opts?: PutOptions): Promise<FileInfo>;
+//#endregion
+export { FileBody, FileInfo, FileObject, FileStore, ListOptions, ListResult, PresignDownloadOptions, PresignUploadOptions, Presigner, PutOptions, collect, toStream, transfer };