@nextlyhq/storage-vercel-blob 0.0.2-alpha.7 → 0.0.2-alpha.71

package/dist/index.cjs

@@ -1,399 +1,1712 @@
-'use strict';
-
-var blob = require('@vercel/blob');
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _vercel_blob = require("@vercel/blob");
+// ../nextly/dist/nextly-error-CwDiSPDF.mjs
+function isDbError(err) {
+	if (!err || typeof err !== "object") return false;
+	const obj = err;
+	return obj.name === "DbError" && typeof obj.kind === "string";
+}
+/**
+* The driver's own code for an error, wherever that driver puts it.
+*
+* Exported so callers that must distinguish one failure from another classify
+* by the SAME extraction this module's mapping uses. A second reader would go
+* looking in a different set of properties and disagree on exactly the drivers
+* whose codes are hardest to find.
+*/
+/**
+* Whether an error is a duplicate-key rejection.
+*
+* Exposed because a plugin inserting into a table with a unique index has to
+* tell "this row already exists" from "the database is broken", and the two
+* arrive as the same thrown object. Derived from the existing SQLSTATE
+* classification rather than by matching driver messages: those differ per
+* driver and per version, and a plugin re-deriving it would be a second
+* implementation of a question this module already answers.
+*/
+/**
+* Whether a driver code says the database was busy: the adapters' own code
+* for a request that waited out `pool.connectionTimeoutMs`, the same on
+* every dialect, or SQLITE_BUSY and its extended codes, another process
+* holding the SQLite file past `busyTimeout`. Neither depends on the dialect,
+* which is what lets {@link isDatabaseBusy} answer without one.
+*/
+function isBusyCode(code) {
+	if (code === void 0) return false;
+	return code === "NEXTLY_POOL_WAIT_TIMEOUT" || code.toUpperCase().startsWith("SQLITE_BUSY");
+}
+/**
+* Whether an error is the database being busy, however it arrives: a DbError
+* of kind "busy", or the raw error an adapter or driver threw.
+*
+* For the boundaries that answer a request with whatever its work threw.
+* `withDbErrors` converts only DbErrors, so a raw driver error reaches them
+* unconverted, and without this it would read as an internal fault rather
+* than a request worth retrying.
+*/
+function isDatabaseBusy(error) {
+	if (isDbError(error)) return error.kind === "busy";
+	return isBusyCode(safeCode(error));
+}
+function safeCode(error) {
+	if (!error || typeof error !== "object") return void 0;
+	const e = error;
+	let c = e.code ?? e.sqlState ?? e.state ?? e.errno ?? void 0;
+	if (!c && typeof e.originalError?.code === "string") c = e.originalError.code;
+	if (!c && typeof e.cause?.code === "string") c = e.cause.code;
+	if (!c && typeof e.severity === "string" && typeof e.code === "string") c = e.code;
+	if (typeof c === "number") return String(c);
+	if (typeof c === "string" && c.length > 0) return c;
+}
+/**
+* Canonical NextlyError codes and their HTTP status mappings.
+*
+* Plugin codes outside this enum must always pass an explicit `statusCode`
+* to the NextlyError constructor (no enum lookup happens for unknown codes).
+*/
+const NEXTLY_ERROR_STATUS = {
+	VALIDATION_ERROR: 400,
+	INVALID_INPUT: 400,
+	AUTH_REQUIRED: 401,
+	AUTH_INVALID_CREDENTIALS: 401,
+	TOKEN_EXPIRED: 401,
+	FORBIDDEN: 403,
+	EMAIL_NOT_VERIFIED: 403,
+	BUILDER_DISABLED: 403,
+	CSRF_FAILED: 403,
+	SETUP_TOKEN_REQUIRED: 403,
+	API_KEY_ROLE_ABOVE_CREATOR: 403,
+	NOT_FOUND: 404,
+	METHOD_NOT_ALLOWED: 405,
+	RANGE_NOT_SATISFIABLE: 416,
+	CONFLICT: 409,
+	DUPLICATE: 409,
+	RATE_LIMITED: 429,
+	PAYLOAD_TOO_LARGE: 413,
+	UNSUPPORTED_MEDIA_TYPE: 415,
+	BUSINESS_RULE_VIOLATION: 422,
+	INTERNAL_ERROR: 500,
+	DATABASE_ERROR: 500,
+	DATABASE_BUSY: 503,
+	EXTERNAL_SERVICE_ERROR: 502,
+	SERVICE_UNAVAILABLE: 503,
+	EXTERNAL_URL_BLOCKED: 400,
+	EXTERNAL_REQUEST_FAILED: 502,
+	FILENAME_INVALID: 400,
+	EXTENSION_BLOCKED: 400,
+	MIME_BLOCKED: 415,
+	MIME_NOT_ALLOWED: 415,
+	SIZE_EXCEEDED: 413,
+	STORAGE_READ_TOO_LARGE: 413,
+	STORAGE_READ_TIMEOUT: 504,
+	STORAGE_READ_UNREACHABLE: 502,
+	MAGIC_BYTE_MISMATCH: 400,
+	SVG_SANITIZATION_FAILED: 400,
+	UNSUPPORTED_FOR_BACKEND: 415,
+	NEXTLY_LEGACY_BOOKKEEPING_DETECTED: 409,
+	NEXTLY_UPGRADE_TABLE_NAME_COLLISION: 409,
+	NEXTLY_UPGRADE_IN_PROGRESS: 409,
+	NEXTLY_MIGRATE_LOCK_BUSY: 409,
+	NEXTLY_BASELINE_LOCK_NOT_HELD: 409,
+	NEXTLY_RESOLVE_LOCK_NOT_HELD: 409,
+	NEXTLY_BOOT_MIGRATIONS_NOT_RUN: 503,
+	NEXTLY_BOOT_MIGRATIONS_PENDING: 503,
+	NEXTLY_CORE_DESTRUCTIVE_REFUSED: 409,
+	NEXTLY_MIGRATION_DRIFT: 409,
+	NEXTLY_MIGRATION_APPLY_FAILED: 500,
+	NEXTLY_MIGRATION_FOREIGN_KEY_VIOLATION: 409,
+	NEXTLY_MIGRATION_PARTIALLY_APPLIED: 500,
+	NEXTLY_MIGRATION_CONCURRENT_RUN: 409,
+	NEXTLY_MIGRATION_FILE_MISSING: 404,
+	NEXTLY_MIGRATION_SNAPSHOT_MISSING: 404,
+	NEXTLY_MIGRATION_RESOLVE_DRIFT: 409,
+	NEXTLY_MIGRATION_RESOLVE_PRECONDITION: 409,
+	NEXTLY_UI_SCHEMA_INVALID: 400,
+	NEXTLY_SCHEMA_SLUG_COLLISION: 409,
+	NEXTLY_SCHEMA_RELATION_TARGET_MISSING: 400,
+	NEXTLY_SCHEMA_RELATION_UNRESOLVED: 400,
+	NEXTLY_SCHEMA_EXTEND_TARGET_UNKNOWN: 400,
+	NEXTLY_SCHEMA_EXTEND_FIELD_DUPLICATE: 409,
+	NEXTLY_SCHEMA_CROSS_PLUGIN_RELATION: 409,
+	NEXTLY_SCHEMA_RENAME_UNKNOWN_TARGET: 400,
+	NEXTLY_PLUGIN_CLIENT_CONFIG_INVALID: 500,
+	NEXTLY_PLUGIN_ADMIN_WIDGET_INVALID: 500,
+	NEXTLY_ADMIN_COMPONENT_MAP_STALE: 500,
+	NEXTLY_PLUGIN_DOCUMENT_VIEW_INVALID: 500,
+	PLUGIN_RESOLUTION_ERROR: 500,
+	PLUGIN_DEPENDENCY_NOT_INSTALLED: 409,
+	PLUGIN_HAS_DEPENDENTS: 409,
+	PLUGIN_UNINSTALL_IRREVERSIBLE: 409,
+	PLUGIN_UNINSTALL_UNCONFIRMED: 409,
+	PLUGIN_SCHEMA_BEHIND: 409,
+	PLUGIN_SCHEMA_UNINSTALLED: 409,
+	PLUGIN_NOT_INSTALLED: 409,
+	PLUGIN_DISABLED: 409,
+	PLUGIN_UNINSTALL_UNFINISHED: 409,
+	PLUGIN_SCHEMA_VERSION_NOT_ADVANCED: 409,
+	PLUGIN_MIGRATION_DROPS_CREATED_SCHEMA: 409,
+	PLUGIN_MIGRATION_ADDS_UNFILLABLE_COLUMN: 409,
+	PLUGIN_MIGRATION_SQL_MISSING: 409,
+	PLUGIN_MIGRATIONS_UNAVAILABLE: 409,
+	DROP_OF_FOREIGN_TABLE: 409,
+	MIGRATION_CHECKSUM_MISMATCH: 409,
+	PLUGIN_MIGRATIONS_OUT_OF_ORDER: 409,
+	PLUGIN_MIGRATION_HISTORY_CHANGED: 409,
+	NEXTLY_ROUTE_COLLISION: 409,
+	NEXTLY_ROUTE_INVALID_PATH: 400,
+	NEXTLY_ROUTE_UNREACHABLE_ROOT: 400,
+	NEXTLY_ROUTE_INVALID_MOUNT: 400,
+	NEXTLY_EMAIL_TRANSPORT_UNAVAILABLE: 503,
+	NEXTLY_CONFIG_TOOLING_UNAVAILABLE: 503,
+	NEXTLY_POSTGRES_SCHEMA_MISMATCH: 500,
+	NEXTLY_POSTGRES_SCHEMA_UNSUPPORTED: 500
+};
+({ ...Object.fromEntries([
+	"VALIDATION_ERROR",
+	"AUTH_REQUIRED",
+	"FORBIDDEN",
+	"NOT_FOUND",
+	"CONFLICT",
+	"PAYLOAD_TOO_LARGE",
+	"UNSUPPORTED_MEDIA_TYPE",
+	"RATE_LIMITED",
+	"EXTERNAL_SERVICE_ERROR",
+	"SERVICE_UNAVAILABLE"
+].map((code) => [NEXTLY_ERROR_STATUS[code], code])) });
+/**
+* The sentence a caller reads for a code, when the failure supplied none.
+*
+* Kept beside the status table because they answer the same question together:
+* a code-less envelope's own `message` is NOT usable here. Those envelopes come
+* from legacy converters that store a raw exception's text, so promoting it
+* would put driver output, table names and internal paths on the wire -- the
+* disclosure the public error shape exists to prevent (spec 13.8).
+*
+* Every entry is generic by design. The specific detail stays in `logContext`
+* for the operator, against the same request id.
+*/
+const GENERIC_PUBLIC_MESSAGE = {
+	VALIDATION_ERROR: "Validation failed.",
+	INVALID_INPUT: "The request could not be processed.",
+	AUTH_REQUIRED: "Authentication required.",
+	FORBIDDEN: "You don't have permission to perform this action.",
+	NOT_FOUND: "Not found.",
+	METHOD_NOT_ALLOWED: "That method is not allowed on this address.",
+	RANGE_NOT_SATISFIABLE: "The requested range is outside the file.",
+	CONFLICT: "The resource has changed since you last loaded it. Please refresh and try again.",
+	DUPLICATE: "Resource already exists.",
+	PAYLOAD_TOO_LARGE: "The request is too large.",
+	UNSUPPORTED_MEDIA_TYPE: "That file type is not supported.",
+	RATE_LIMITED: "Too many requests. Please try again later.",
+	EXTERNAL_SERVICE_ERROR: "An upstream service failed.",
+	SERVICE_UNAVAILABLE: "The service is temporarily unavailable.",
+	DATABASE_BUSY: "The database is busy. Please try again shortly.",
+	INTERNAL_ERROR: "An unexpected error occurred."
+};
+/** The generic sentence for a code; the internal one for anything unlisted. */
+function genericPublicMessage(code) {
+	return GENERIC_PUBLIC_MESSAGE[code] ?? GENERIC_PUBLIC_MESSAGE.INTERNAL_ERROR;
+}
+/**
+* Default mapping from DbErrorKind to NextlyError contract. Used by
+* `NextlyError.fromDatabaseError`. Public messages are intentionally generic
+* per spec §13.8 — no DB driver text, no constraint names, no field hints.
+*
+* `satisfies Record<DbErrorKind, ...>` makes the mapping exhaustive at
+* compile time: adding a new DbErrorKind without updating this table is a
+* type error.
+*/
+const DB_ERROR_MAPPING = {
+	"unique-violation": {
+		code: "DUPLICATE",
+		statusCode: 409,
+		publicMessage: "Resource already exists."
+	},
+	"fk-violation": {
+		code: "VALIDATION_ERROR",
+		statusCode: 400,
+		publicMessage: "Referenced record does not exist."
+	},
+	"not-null-violation": {
+		code: "VALIDATION_ERROR",
+		statusCode: 400,
+		publicMessage: "A required field is missing."
+	},
+	constraint: {
+		code: "VALIDATION_ERROR",
+		statusCode: 400,
+		publicMessage: "The provided data violates a constraint."
+	},
+	deadlock: {
+		code: "CONFLICT",
+		statusCode: 409,
+		publicMessage: "The operation could not be completed. Please retry."
+	},
+	"serialization-failure": {
+		code: "CONFLICT",
+		statusCode: 409,
+		publicMessage: "The operation could not be completed. Please retry."
+	},
+	busy: {
+		code: "DATABASE_BUSY",
+		statusCode: NEXTLY_ERROR_STATUS.DATABASE_BUSY,
+		publicMessage: genericPublicMessage("DATABASE_BUSY"),
+		publicData: { retryAfterSeconds: 5 }
+	},
+	timeout: {
+		code: "DATABASE_ERROR",
+		statusCode: 500,
+		publicMessage: "The operation timed out. Please try again."
+	},
+	"connection-lost": {
+		code: "DATABASE_ERROR",
+		statusCode: 500,
+		publicMessage: "A temporary database error occurred. Please try again."
+	},
+	syntax: {
+		code: "INTERNAL_ERROR",
+		statusCode: 500,
+		publicMessage: "An unexpected error occurred."
+	},
+	internal: {
+		code: "INTERNAL_ERROR",
+		statusCode: 500,
+		publicMessage: "An unexpected error occurred."
+	}
+};
+const NEXTLY_ERROR_BRAND = Symbol.for("nextly/NextlyError");
+function hasBrand(value) {
+	if (value === null || typeof value !== "object" && typeof value !== "function") return false;
+	return value[NEXTLY_ERROR_BRAND] === true;
+}
+/**
+* Unified error class for Nextly. Used at every throw site across services,
+* direct API, auth, and plugins. Carries two distinct payloads:
+*
+*   - Public  (`code`, `publicMessage`, `publicData`, `statusCode`, `messageKey`)
+*     sent in HTTP responses and Server Action results.
+*   - Log     (`logMessage`, `logContext`, `cause`, stack trace)
+*     written to the server logger; never serialised to the wire.
+*
+* Use the static factories (notFound, forbidden, validation, ...) for the
+* common cases. Use the free-form constructor for plugin codes or one-off
+* shapes.
+*/
+var NextlyError = class NextlyError extends Error {
+	code;
+	statusCode;
+	publicMessage;
+	publicData;
+	messageKey;
+	logMessage;
+	logContext;
+	cause;
+	timestamp;
+	constructor(opts) {
+		super(opts.publicMessage);
+		this.name = "NextlyError";
+		this.code = opts.code;
+		this.publicMessage = opts.publicMessage;
+		this.publicData = opts.publicData;
+		this.messageKey = opts.messageKey;
+		this.logMessage = opts.logMessage;
+		this.logContext = opts.logContext;
+		this.cause = opts.cause;
+		this.timestamp = /* @__PURE__ */ new Date();
+		this.statusCode = NextlyError.resolveStatusCode(opts);
+		Error.captureStackTrace?.(this, NextlyError);
+	}
+	static {
+		NextlyError.prototype[NEXTLY_ERROR_BRAND] = true;
+	}
+	static resolveStatusCode(opts) {
+		if (typeof opts.statusCode === "number") return opts.statusCode;
+		if (opts.code in NEXTLY_ERROR_STATUS) return NEXTLY_ERROR_STATUS[opts.code];
+		return 500;
+	}
+	/** HTTP-safe JSON. Strips logMessage / logContext / cause / stack. */
+	toResponseJSON(requestId) {
+		const json = {
+			code: String(this.code),
+			message: this.publicMessage,
+			requestId
+		};
+		if (this.messageKey) json.messageKey = this.messageKey;
+		if (this.publicData !== void 0) json.data = this.publicData;
+		return json;
+	}
+	/** Operator-facing JSON for log lines. Includes everything. */
+	toLogJSON(requestId) {
+		return {
+			code: this.code,
+			statusCode: this.statusCode,
+			publicMessage: this.publicMessage,
+			messageKey: this.messageKey,
+			logMessage: this.logMessage,
+			logContext: this.logContext,
+			cause: this.cause ? {
+				name: this.cause.name,
+				message: this.cause.message,
+				stack: this.cause.stack
+			} : void 0,
+			timestamp: this.timestamp.toISOString(),
+			requestId
+		};
+	}
+	static invalidCredentials(opts) {
+		return new NextlyError({
+			code: "AUTH_INVALID_CREDENTIALS",
+			publicMessage: "Invalid email or password.",
+			logMessage: "Login failed",
+			logContext: opts?.logContext
+		});
+	}
+	/**
+	* The password was correct and the address is unverified. Thrown only once
+	* the password is proven, so only someone who holds it learns the address
+	* is unverified; every other refusal stays
+	* {@link NextlyError.invalidCredentials}.
+	*/
+	static emailNotVerified(opts) {
+		return new NextlyError({
+			code: "EMAIL_NOT_VERIFIED",
+			publicMessage: "Verify your email address to sign in. Check your inbox for the link.",
+			logMessage: "Login refused: email not verified",
+			logContext: opts?.logContext
+		});
+	}
+	static authRequired(opts) {
+		return new NextlyError({
+			code: "AUTH_REQUIRED",
+			publicMessage: "Authentication required.",
+			logContext: opts?.logContext
+		});
+	}
+	/**
+	* Distinct from `authRequired`: the caller was authenticated but the
+	* session token expired. Clients key on the TOKEN_EXPIRED *code* to
+	* silently refresh and retry rather than redirecting to login; the public
+	* message stays the generic spec §13.6 string ("Authentication required.")
+	* so the wire never reveals the session state — same as `authRequired`.
+	*/
+	static tokenExpired(opts) {
+		return new NextlyError({
+			code: "TOKEN_EXPIRED",
+			publicMessage: "Authentication required.",
+			logContext: opts?.logContext
+		});
+	}
+	static notFound(opts) {
+		return new NextlyError({
+			code: "NOT_FOUND",
+			publicMessage: opts?.message ?? "Not found.",
+			cause: opts?.cause,
+			logContext: opts?.logContext
+		});
+	}
+	static forbidden(opts) {
+		return new NextlyError({
+			code: "FORBIDDEN",
+			publicMessage: "You don't have permission to perform this action.",
+			cause: opts?.cause,
+			logContext: opts?.logContext
+		});
+	}
+	/**
+	* A collection, Single or component defined in code, which is changed by
+	* changing its code and not from here. Forbidden, and the message says so:
+	* it is a fact about the thing, not about the caller's permissions, so it
+	* names no permission and no policy. The lock's detail goes to the log
+	* through `logContext`.
+	*/
+	static definedInCode(opts) {
+		return new NextlyError({
+			code: "FORBIDDEN",
+			publicMessage: `This ${opts.thing} is defined in code, so it can't be ${opts.change === "change" ? "changed" : "deleted"} here.`,
+			logContext: opts.logContext
+		});
+	}
+	/**
+	* An autosave where the collection or Single does not autosave: its owner
+	* switched autosave off, or it keeps no drafts to autosave into. Forbidden,
+	* and the message says so, since it is a setting and not a permission.
+	*/
+	static autosaveOff(opts) {
+		return new NextlyError({
+			code: "FORBIDDEN",
+			publicMessage: `Autosave is turned off for this ${opts.scopeKind === "single" ? "Single" : "collection"}.`,
+			logContext: opts.logContext
+		});
+	}
+	/**
+	* An API key refused because its role allows more than the person creating
+	* it may do. The sentence is FORBIDDEN's and names no permission; which one
+	* exceeded goes to the log through `logContext`. The code is its own, so a
+	* client can tell "choose a smaller role" from plain FORBIDDEN.
+	*/
+	static apiKeyRoleAboveCreator(opts) {
+		return new NextlyError({
+			code: "API_KEY_ROLE_ABOVE_CREATOR",
+			publicMessage: genericPublicMessage("FORBIDDEN"),
+			logContext: opts?.logContext
+		});
+	}
+	/**
+	* A cookie-authenticated write refused because its origin or CSRF token did
+	* not check out. The public message names no detail of which check failed;
+	* that goes to the log through `logMessage`.
+	*/
+	static csrfFailed(opts) {
+		return new NextlyError({
+			code: "CSRF_FAILED",
+			publicMessage: "This request could not be verified. Reload the page and try again.",
+			logMessage: opts?.logMessage,
+			logContext: opts?.logContext
+		});
+	}
+	/**
+	* A call the caller got wrong, where naming the mistake IS the value of the
+	* error.
+	*
+	* The only factory that takes its public message from the caller. The
+	* generic messages elsewhere exist so an HTTP response cannot leak internal
+	* detail; this one is for arguments and configuration a developer controls
+	* and must be told about — a missing option, an unusable combination — where
+	* `internal()` would reduce the one useful sentence to "An unexpected error
+	* occurred." Do not pass user-supplied data through it.
+	*/
+	static invalidInput(opts) {
+		return new NextlyError({
+			code: "INVALID_INPUT",
+			publicMessage: opts.message,
+			logContext: opts.logContext
+		});
+	}
+	static validation(opts) {
+		return new NextlyError({
+			code: "VALIDATION_ERROR",
+			publicMessage: "Validation failed.",
+			publicData: { errors: opts.errors },
+			cause: opts.cause,
+			logContext: opts.logContext
+		});
+	}
+	static conflict(opts) {
+		return new NextlyError({
+			code: "CONFLICT",
+			publicMessage: opts?.message ?? "The resource has changed since you last loaded it. Please refresh and try again.",
+			publicData: opts?.data,
+			cause: opts?.cause,
+			logContext: {
+				reason: opts?.reason,
+				...opts?.logContext
+			}
+		});
+	}
+	static duplicate(opts) {
+		return new NextlyError({
+			code: "DUPLICATE",
+			publicMessage: "Resource already exists.",
+			logContext: opts?.logContext
+		});
+	}
+	static rateLimited(opts) {
+		return new NextlyError({
+			code: "RATE_LIMITED",
+			publicMessage: "Too many requests. Please try again later.",
+			publicData: opts?.retryAfterSeconds !== void 0 ? { retryAfterSeconds: opts.retryAfterSeconds } : void 0,
+			logContext: opts?.logContext
+		});
+	}
+	/**
+	* A request that waited `pool.connectionTimeoutMs` for a database
+	* connection and was given none. The statement or transaction that waited
+	* never ran; work committed before it stays committed. The same error
+	* `fromDatabaseError` gives a busy DbError, from the same table row.
+	*/
+	static databaseBusy(opts) {
+		const busy = DB_ERROR_MAPPING.busy;
+		return new NextlyError({
+			code: busy.code,
+			statusCode: busy.statusCode,
+			publicMessage: busy.publicMessage,
+			publicData: busy.publicData,
+			cause: opts?.cause,
+			logContext: opts?.logContext
+		});
+	}
+	/**
+	* What a request boundary answers with for a thrown value that is not a
+	* NextlyError: "database busy" when the request waited out its bound for a
+	* connection, which is retryable and no fault of the server's code, and an
+	* internal error for anything else.
+	*
+	* The busy case has to be read here because it usually arrives raw:
+	* `withDbErrors` converts only DbErrors, so a driver's error passes through
+	* services unconverted to the boundary that answers the request.
+	*/
+	static fromUnexpected(error) {
+		return NextlyError.busyOr(error, () => NextlyError.internal({ cause: error instanceof Error ? error : void 0 }));
+	}
+	/**
+	* "Database busy" when `error` is a request that waited out its bound for
+	* a connection, and `otherwise()` for anything else.
+	*
+	* For a boundary that answers an unexpected failure with an error of its
+	* own choosing rather than an internal one (a 503 for a flow that must not
+	* answer on incomplete data), so that a busy database still answers there
+	* as it does everywhere else. `fromUnexpected` is this rule with the
+	* internal error as its fallback.
+	*/
+	static busyOr(error, otherwise) {
+		if (!isDatabaseBusy(error)) return otherwise();
+		return NextlyError.databaseBusy({ cause: error instanceof Error ? error : void 0 });
+	}
+	static internal(opts) {
+		return new NextlyError({
+			code: "INTERNAL_ERROR",
+			publicMessage: "An unexpected error occurred.",
+			cause: opts?.cause,
+			logContext: opts?.logContext
+		});
+	}
+	static serviceUnavailable(opts) {
+		return new NextlyError({
+			code: "SERVICE_UNAVAILABLE",
+			publicMessage: opts?.publicMessage ?? "Service unavailable. Please try again later.",
+			logMessage: opts?.logMessage,
+			cause: opts?.cause,
+			logContext: opts?.logContext
+		});
+	}
+	/**
+	* Convert a DbError (or arbitrary unknown thrown by the DB layer) to a
+	* NextlyError with a generic public message and rich logContext. Used by
+	* `withDbErrors` for auto-conversion (Pattern A) and by services that
+	* catch DB errors at boundaries (Pattern B). Spec §8.2 mapping table.
+	*
+	* Never leaks DB driver text, constraint names, or table names into
+	* `publicMessage`. All DB context goes into `logContext`. The original
+	* DbError is preserved as `cause`.
+	*/
+	static fromDatabaseError(error) {
+		if (isDbError(error)) {
+			const mapping = DB_ERROR_MAPPING[error.kind];
+			const logContext = {
+				dbKind: error.kind,
+				dialect: error.dialect
+			};
+			if (error.code !== void 0) logContext.dbCode = error.code;
+			if (error.meta !== void 0) logContext.meta = error.meta;
+			return new NextlyError({
+				code: mapping.code,
+				statusCode: mapping.statusCode,
+				publicMessage: mapping.publicMessage,
+				publicData: "publicData" in mapping ? mapping.publicData : void 0,
+				logMessage: "Database error",
+				logContext,
+				cause: error
+			});
+		}
+		return new NextlyError({
+			code: "INTERNAL_ERROR",
+			statusCode: 500,
+			publicMessage: "An unexpected error occurred.",
+			logMessage: "Non-DbError passed to fromDatabaseError",
+			cause: error instanceof Error ? error : void 0,
+			logContext: error instanceof Error ? void 0 : { value: String(error) }
+		});
+	}
+	static is(err) {
+		return hasBrand(err);
+	}
+	static isCode(err, code) {
+		return hasBrand(err) && err.code === code;
+	}
+	static isNotFound(err) {
+		return NextlyError.isCode(err, "NOT_FOUND");
+	}
+	static isValidation(err) {
+		return NextlyError.isCode(err, "VALIDATION_ERROR");
+	}
+	static isAuthRequired(err) {
+		return NextlyError.isCode(err, "AUTH_REQUIRED");
+	}
+	static isForbidden(err) {
+		return NextlyError.isCode(err, "FORBIDDEN");
+	}
+	static isConflict(err) {
+		return NextlyError.isCode(err, "CONFLICT");
+	}
+	static isRateLimited(err) {
+		return NextlyError.isCode(err, "RATE_LIMITED");
+	}
+};
+// ../nextly/dist/get-trusted-client-ip-CYEbmLA3.mjs
+/**
+* A dotted-quad IPv4 address as an unsigned 32-bit integer, or null when it is
+* not one. Shared by the client-address, refresh-binding and outbound-URL
+* prefix checks.
+*/
+function ipv4ToInt(ip) {
+	const parts = ip.split(".");
+	if (parts.length !== 4) return null;
+	let acc = 0;
+	for (const p of parts) {
+		const n = Number(p);
+		if (!Number.isInteger(n) || n < 0 || n > 255) return null;
+		acc = acc << 8 | n;
+	}
+	return acc >>> 0;
+}
+// ../nextly/dist/validate-external-url-CnZrcJdP.mjs
+const IPV4_RE = /^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$/;
+/**
+* IPv4 CIDR ranges that must NEVER be the destination of an outbound
+* fetch sourced from a user-controllable URL. Listed roughly by RFC.
+*/
+const PRIVATE_IPV4_CIDRS = [
+	"0.0.0.0/8",
+	"10.0.0.0/8",
+	"100.64.0.0/10",
+	"127.0.0.0/8",
+	"169.254.0.0/16",
+	"172.16.0.0/12",
+	"192.0.0.0/24",
+	"192.0.2.0/24",
+	"192.168.0.0/16",
+	"198.18.0.0/15",
+	"198.51.100.0/24",
+	"203.0.113.0/24",
+	"224.0.0.0/4",
+	"240.0.0.0/4"
+];
+/**
+* Cloud-metadata hostnames. These often resolve to private IPs and the
+* private-IP block catches them, but we reject by hostname first so the
+* error message is clear.
+*/
+const CLOUD_METADATA_HOSTS = /* @__PURE__ */ new Set([
+	"metadata.google.internal",
+	"metadata.googleapis.com",
+	"metadata"
+]);
+/**
+* An outbound URL refused for SSRF safety. Extends `NextlyError` (the package's
+* canonical error) so throw sites honor the error contract, while remaining a
+* distinct class the callers (e.g. the form-builder webhook handler) match with
+* `instanceof`.
+*/
+var ExternalUrlError = class extends NextlyError {
+	url;
+	constructor(message, url) {
+		super({
+			code: "EXTERNAL_URL_BLOCKED",
+			publicMessage: message,
+			logContext: { url }
+		});
+		this.url = url;
+		this.name = "ExternalUrlError";
+	}
+};
+/** Validate a URL for outbound fetch. Throws `ExternalUrlError` on rejection. */
+async function validateExternalUrl(rawUrl, options = {}) {
+	let parsed;
+	try {
+		parsed = new URL(rawUrl);
+	} catch {
+		throw new ExternalUrlError("Invalid URL", rawUrl);
+	}
+	const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+	const isLocalhostHostname = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+	const baseProtocols = options.allowedProtocols ?? ["https:"];
+	const protocols = options.allowLocalhost && isLocalhostHostname ? [...baseProtocols, "http:"] : baseProtocols;
+	if (!protocols.includes(parsed.protocol)) throw new ExternalUrlError(`Protocol ${parsed.protocol} not allowed (allowed: ${protocols.join(", ")})`, rawUrl);
+	if (CLOUD_METADATA_HOSTS.has(hostname)) throw new ExternalUrlError(`Cloud-metadata hostname rejected: ${parsed.hostname}`, rawUrl);
+	if (IPV4_RE.test(hostname)) {
+		if (!isPublicIpv4(hostname, options.allowLocalhost === true && hostname === "127.0.0.1")) throw new ExternalUrlError(`Resolved to non-public IP: ${hostname}`, rawUrl);
+		return {
+			url: parsed,
+			pinnedIp: hostname,
+			family: 4
+		};
+	}
+	if (hostname.includes(":")) {
+		if (!isPublicIpv6(hostname, options.allowLocalhost === true && hostname === "::1")) throw new ExternalUrlError(`Resolved to non-public IP: ${hostname}`, rawUrl);
+		return {
+			url: parsed,
+			pinnedIp: hostname,
+			family: 6
+		};
+	}
+	const { lookup } = await import("node:dns/promises");
+	let addresses;
+	try {
+		addresses = await lookup(hostname, { all: true });
+	} catch (err) {
+		throw new ExternalUrlError(`DNS lookup failed: ${err.message}`, rawUrl);
+	}
+	if (addresses.length === 0) throw new ExternalUrlError("No IPs returned for host", rawUrl);
+	for (const { address, family } of addresses) {
+		const allow = options.allowLocalhost === true && isLocalhostHostname && family === 4;
+		if (!(family === 4 ? isPublicIpv4(address, allow) : isPublicIpv6(address, allow))) throw new ExternalUrlError(`Resolved to non-public IP: ${address}`, rawUrl);
+	}
+	const first = addresses[0];
+	return {
+		url: parsed,
+		pinnedIp: first.address,
+		family: first.family === 6 ? 6 : 4
+	};
+}
+/** Default response body cap: reject anything larger before buffering it all. */
+/**
+* How many bytes a bounded external read may buffer, absent a caller's own cap.
+*
+* Exported for the same reason as the deadline below: an adapter that never
+* touches `safeFetch` still owes callers this default, and restating the number
+* gives the tree two that drift.
+*/
+const DEFAULT_MAX_RESPONSE_BYTES = 10485760;
+/** Default overall deadline covering DNS + connect + TLS + response. */
+/**
+* How long a bounded external read may take, absent a caller's own limit.
+*
+* Exported so a caller that must begin the clock EARLIER — a storage adapter
+* bounding a metadata lookup as well as the fetch that follows — uses this
+* number rather than restating it. Two spellings of one default agree today and
+* drift the first time either is tuned.
+*/
+const DEFAULT_TIMEOUT_MS = 3e4;
+/**
+* Raised for fetch-phase failures that are NOT SSRF rejections: an over-large
+* response body, the overall deadline elapsing, or an undecodable content
+* encoding. Extends `NextlyError` (the canonical error contract) while staying a
+* distinct class, so a caller can tell "URL refused for safety"
+* (`ExternalUrlError`) apart from "the request itself failed".
+*/
+var SafeFetchError = class extends NextlyError {
+	url;
+	reason;
+	status;
+	constructor(message, url, reason, status) {
+		super({
+			code: "EXTERNAL_REQUEST_FAILED",
+			publicMessage: message,
+			logContext: {
+				url,
+				reason
+			}
+		});
+		this.url = url;
+		this.reason = reason;
+		this.status = status;
+		this.name = "SafeFetchError";
+	}
+};
+/**
+* Build a `dns.lookup`-compatible function that ignores the hostname and
+* always resolves to `ip`/`family`. Handing this to `http(s).request` forces
+* the socket to dial the exact address `validateExternalUrl` already vetted,
+* closing the DNS-rebinding window where a second resolution at connect time
+* could return a private IP. Not re-exported from the package barrel; exported
+* for the plugin `ctx.fetch` transport, which pins its vetted address the same
+* way, and so the rebinding invariant can be unit-tested directly.
+*/
+function createPinnedLookup(ip, family) {
+	return (_hostname, options, callback) => {
+		if (options && options.all) callback(null, [{
+			address: ip,
+			family
+		}]);
+		else callback(null, ip, family);
+	};
+}
+/**
+* Validate `rawUrl` then fetch it with the validated IP pinned at the socket.
+* The convenience wrapper for the common case (webhook delivery, email
+* attachment fetch). Node-runtime only.
+*
+* DNS is resolved once by `validateExternalUrl`; `createPinnedLookup` forces
+* the connection to that same address, so an attacker's DNS cannot rebind the
+* request to a private host between validation and connect. Redirects are not
+* followed, the body is capped at `maxResponseBytes`, and the request is
+* bounded by `timeoutMs`.
+*/
+async function safeFetch(rawUrl, options = {}) {
+	const { allowLocalhost, allowedProtocols, method, headers, body, signal, maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+	const controller = new AbortController();
+	const forwardAbort = () => controller.abort(signal?.reason);
+	if (signal) {
+		if (signal.aborted) controller.abort(signal.reason);
+		else signal.addEventListener("abort", forwardAbort, { once: true });
+	}
+	const timer = setTimeout(() => controller.abort(new SafeFetchError(`Request exceeded ${timeoutMs}ms`, rawUrl, "timeout")), timeoutMs);
+	try {
+		return await pinnedFetch(await abortable(validateExternalUrl(rawUrl, {
+			allowLocalhost,
+			allowedProtocols
+		}), controller.signal), {
+			method,
+			headers,
+			body,
+			signal: controller.signal,
+			maxResponseBytes
+		});
+	} finally {
+		clearTimeout(timer);
+		if (signal) signal.removeEventListener("abort", forwardAbort);
+	}
+}
+/**
+* The signal's abort reason as an `Error`. Our own aborts carry a
+* `SafeFetchError` (timeout); a caller's `AbortController.abort()` carries a
+* DOMException `AbortError`; anything else (a non-Error reason) is surfaced as
+* a standard `AbortError` so downstream `name === "AbortError"` checks hold.
+*/
+function abortError(signal) {
+	const reason = signal.reason;
+	if (reason instanceof Error) return reason;
+	return new DOMException("The operation was aborted", "AbortError");
+}
+/**
+* Resolve `promise`, but reject with the signal's reason if it aborts first.
+* Lets a phase that runs before the request (DNS validation) share the overall
+* deadline and caller cancellation.
+*/
+function abortable(promise, signal) {
+	if (signal.aborted) return Promise.reject(abortError(signal));
+	let onAbort;
+	const aborted = new Promise((_resolve, reject) => {
+		onAbort = () => reject(abortError(signal));
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	return Promise.race([promise, aborted]).finally(() => signal.removeEventListener("abort", onAbort));
+}
+/**
+* Issue the request over `node:http`/`node:https` with the validated IP pinned
+* via a custom `lookup`, then adapt the Node response into a WHATWG `Response`.
+* `agent: false` forces a fresh socket per call so no pooled connection can
+* reuse a differently-resolved address. The overall deadline is enforced by the
+* caller through `init.signal`, so there is no separate timer here.
+*/
+async function pinnedFetch(validated, init) {
+	const { url, pinnedIp, family } = validated;
+	const httpMod = url.protocol === "https:" ? await import("node:https") : await import("node:http");
+	const zlib = await import("node:zlib");
+	const lookup = createPinnedLookup(pinnedIp, family);
+	const outHeaders = toOutgoingHeaders(init.headers);
+	if (init.body != null) {
+		delete outHeaders["transfer-encoding"];
+		outHeaders["content-length"] = String(typeof init.body === "string" ? Buffer.byteLength(init.body) : init.body.byteLength);
+	}
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const settle = (fn) => {
+			if (settled) return;
+			settled = true;
+			fn();
+		};
+		const failure = (err) => init.signal.aborted ? abortError(init.signal) : err;
+		const req = httpMod.request(url, {
+			method: init.method ?? "GET",
+			headers: outHeaders,
+			lookup,
+			agent: false,
+			signal: init.signal
+		}, (res) => {
+			const chunks = [];
+			let received = 0;
+			res.on("data", (chunk) => {
+				received += chunk.length;
+				if (received > init.maxResponseBytes) {
+					res.destroy();
+					req.destroy();
+					settle(() => reject(new SafeFetchError(`Response body exceeded ${init.maxResponseBytes} bytes`, url.href, "response-too-large", res.statusCode)));
+					return;
+				}
+				chunks.push(chunk);
+			});
+			res.on("end", () => {
+				const decoded = decodeBody(Buffer.concat(chunks), res.headers["content-encoding"], zlib, init.maxResponseBytes, url.href, res.statusCode);
+				if (decoded instanceof SafeFetchError) {
+					settle(() => reject(decoded));
+					return;
+				}
+				settle(() => resolve(toWhatwgResponse(res, decoded.body, decoded.decoded)));
+			});
+			res.on("error", (err) => settle(() => reject(failure(err))));
+		});
+		req.on("error", (err) => settle(() => reject(failure(err))));
+		if (!req.destroyed) {
+			if (init.body != null) req.write(init.body);
+			req.end();
+		}
+	});
+}
+/**
+* Normalize a `HeadersInit` into Node's outgoing-header shape. Header names are
+* lowercased (they are case-insensitive) so later framing checks
+* (`content-length`) and the Host strip are reliable regardless of caller
+* casing. A caller-supplied `Host` is dropped: it is derived from the validated
+* URL, and honoring an override would let Host-based routing reach an internal
+* vhost behind a validated public IP, defeating the SSRF pin.
+*/
+function toOutgoingHeaders(headers) {
+	const out = {};
+	if (!headers) return out;
+	const add = (rawKey, value) => {
+		const key = rawKey.toLowerCase();
+		if (key === "host") return;
+		const existing = out[key];
+		out[key] = existing === void 0 ? value : [].concat(existing, value);
+	};
+	if (headers instanceof Headers) headers.forEach((value, key) => add(key, value));
+	else if (Array.isArray(headers)) for (const [key, value] of headers) add(key, value);
+	else for (const [key, value] of Object.entries(headers)) add(key, value);
+	return out;
+}
+/**
+* Adapt a Node `IncomingMessage` + buffered body into a WHATWG `Response`.
+* Total by construction: a header the WHATWG layer rejects is skipped and the
+* status is clamped to a constructible range, so this never throws (a throw
+* would otherwise escape the `end` handler as an uncaught error).
+*/
+function toWhatwgResponse(res, body, stripContentHeaders) {
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(res.headers)) {
+		if (value == null) continue;
+		const lower = key.toLowerCase();
+		if (stripContentHeaders && (lower === "content-encoding" || lower === "content-length")) continue;
+		const values = Array.isArray(value) ? value : [value];
+		for (const v of values) try {
+			headers.append(key, v);
+		} catch {}
+	}
+	const raw = res.statusCode ?? 502;
+	const status = raw >= 200 && raw <= 599 ? raw : 502;
+	const nullBody = status === 204 || status === 205 || status === 304;
+	const bytes = new Uint8Array(body.byteLength);
+	bytes.set(body);
+	return new Response(nullBody ? null : bytes, {
+		status,
+		statusText: res.statusMessage ?? "",
+		headers
+	});
+}
+/**
+* Content-decode a response body per its `Content-Encoding`. node:http returns
+* raw wire bytes (unlike global fetch), so gzip/deflate/br bodies are inflated
+* here to preserve the previous behavior. `maxOutputLength` bounds the inflated
+* size, turning a decompression bomb into a `SafeFetchError` rather than an OOM.
+* Returns the (possibly decoded) buffer, or a `SafeFetchError` on failure.
+*/
+function decodeBody(buf, encoding, zlib, cap, url, status) {
+	if (!encoding) return {
+		body: buf,
+		decoded: false
+	};
+	if (buf.length === 0) return {
+		body: buf,
+		decoded: true
+	};
+	const layers = encoding.split(",").map((e) => e.trim().toLowerCase()).filter(Boolean);
+	const opts = { maxOutputLength: cap };
+	let current = buf;
+	let decoded = false;
+	try {
+		for (let i = layers.length - 1; i >= 0; i--) {
+			const enc = layers[i];
+			if (enc === "identity") continue;
+			if (enc === "gzip" || enc === "x-gzip") current = zlib.gunzipSync(current, opts);
+			else if (enc === "br") current = zlib.brotliDecompressSync(current, opts);
+			else if (enc === "deflate") try {
+				current = zlib.inflateSync(current, opts);
+			} catch (inflateErr) {
+				if (errorCode(inflateErr) === "ERR_BUFFER_TOO_LARGE") throw inflateErr;
+				current = zlib.inflateRawSync(current, opts);
+			}
+			else {
+				if (decoded) return new SafeFetchError(`Cannot fully decode content-encoding "${encoding}"`, url, "decode-failed", status);
+				return {
+					body: buf,
+					decoded: false
+				};
+			}
+			decoded = true;
+		}
+		return {
+			body: current,
+			decoded
+		};
+	} catch (err) {
+		const tooLarge = errorCode(err) === "ERR_BUFFER_TOO_LARGE";
+		return new SafeFetchError(tooLarge ? `Decoded ${encoding} response body exceeded the size cap` : `Failed to decode ${encoding} response body`, url, tooLarge ? "response-too-large" : "decode-failed", status);
+	}
+}
+/** The `.code` of a Node system error, if present. */
+function errorCode(err) {
+	if (err != null && typeof err === "object" && "code" in err) {
+		const code = err.code;
+		return typeof code === "string" ? code : void 0;
+	}
+}
+function isIpv4InCidr(intIp, cidr) {
+	const [addr, prefixRaw] = cidr.split("/");
+	const intCidr = ipv4ToInt(addr);
+	if (intCidr === null) return false;
+	const prefix = Number(prefixRaw);
+	if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) return false;
+	const mask = prefix === 0 ? 0 : -1 >>> 32 - prefix << 32 - prefix;
+	return (intIp & mask) >>> 0 === (intCidr & mask) >>> 0;
+}
+function isPublicIpv4(addr, allowLoopback) {
+	const intIp = ipv4ToInt(addr);
+	if (intIp === null) return false;
+	if (allowLoopback && addr === "127.0.0.1") return true;
+	for (const cidr of PRIVATE_IPV4_CIDRS) if (isIpv4InCidr(intIp, cidr)) return false;
+	return true;
+}
+/**
+* Extract the embedded IPv4 of an IPv4-mapped IPv6 address, or null. Handles
+* both the dotted form (`::ffff:1.2.3.4`) and the hex form (`::ffff:7f00:1`)
+* that `URL.hostname` normalizes the dotted literal to — the latter would
+* otherwise skip the IPv4 denylist and pin, e.g., loopback as public.
+*/
+function mappedIpv4(lower) {
+	const dotted = lower.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+	if (dotted) return dotted[1];
+	const hex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+	if (hex) {
+		const hi = parseInt(hex[1], 16);
+		const lo = parseInt(hex[2], 16);
+		return [
+			hi >> 8,
+			hi & 255,
+			lo >> 8,
+			lo & 255
+		].join(".");
+	}
+	return null;
+}
+function isPublicIpv6(addr, allowLoopback) {
+	const lower = addr.toLowerCase();
+	if (allowLoopback && lower === "::1") return true;
+	const mapped = mappedIpv4(lower);
+	if (mapped) return isPublicIpv4(mapped, allowLoopback);
+	if (lower === "::" || lower === "::1") return false;
+	const firstHextet = lower.split(":")[0] || "";
+	if (firstHextet.startsWith("fc") || firstHextet.startsWith("fd")) return false;
+	if (firstHextet.startsWith("fe8") || firstHextet.startsWith("fe9")) return false;
+	if (firstHextet.startsWith("fea") || firstHextet.startsWith("feb")) return false;
+	if (firstHextet.startsWith("ff")) return false;
+	return true;
+}
+// ../nextly/dist/storage/read-errors.mjs
+/**
+* The one way the storage layer says a read exceeded the caller's cap.
+*
+* `StorageReadOptions.maxBytes` is part of the adapter contract, so what happens
+* when it is exceeded belongs to the contract too. Without this each backend
+* refuses in its own vocabulary — the URL-addressed ones through a fetch error
+* carrying a `reason`, S3 through whatever its own code threw — and a caller
+* wanting to tell "too large" from "could not read" has to know which adapter it
+* is talking to. That is the thing an adapter contract exists to stop.
+*
+* Distinct from a generic internal failure because callers ACT on the
+* difference. The email attachment path answers an over-cap read with
+* `ATTACHMENT_SIZE_EXCEEDED`, which tells an author to attach something smaller;
+* a storage failure tells them nothing they can act on. Collapsing the two turns
+* a fixable refusal into an opaque error, which is the same conflation this
+* contract already draws between a missing key and an unreachable store.
+*
+* @module storage/read-errors
+*/
+/**
+* A read refused because the object is larger than the caller allowed.
+*
+* Carries the numbers rather than only a message, so a caller can say what the
+* limit was without parsing prose — and so the message itself stays free of the
+* key, which should not travel to whoever asked for the file.
+*/
+var StorageReadTooLargeError = class extends NextlyError {
+	path;
+	maxBytes;
+	size;
+	constructor(path, maxBytes, size) {
+		super({
+			code: "STORAGE_READ_TOO_LARGE",
+			publicMessage: "The stored file is larger than the limit for this read.",
+			logContext: {
+				path,
+				maxBytes,
+				...size === void 0 ? {} : { size }
+			}
+		});
+		this.path = path;
+		this.maxBytes = maxBytes;
+		this.size = size;
+	}
+};
+// ../nextly/dist/storage/fetch-stored-bytes.mjs
+/**
+* Reading bytes back from a storage service that only exposes them over HTTP.
+*
+* The local adapter reads from disk and S3 reads through its own SDK, so
+* neither needs this. The services that address a file by URL — Vercel Blob,
+* UploadThing — all end up doing the same three things, and doing them the same
+* way matters more than it looks: each step below is a place where the obvious
+* shortcut reports the wrong thing to a caller who may act on it.
+*
+* Built on {@link safeFetch} rather than on a bare `fetch`, because "read a
+* remote object into memory" already has an implementation here that caps the
+* body, bounds the request and refuses an address that resolves somewhere
+* private. A second capped fetch beside it would be two answers to one
+* question, and the two would drift the first time either learned something.
+* Measured: it costs an adapter package about 80K, against the 1MB the whole
+* storage barrel costs.
+*
+* @module storage/fetch-stored-bytes
+*/
+/**
+* Fetch a stored object's bytes from the URL its service issued.
+*
+* Separates the two answers a read can have, which is the whole reason this is
+* a function rather than three lines inlined twice.
+*
+* `null` means the object is NOT THERE — an ordinary fact about the store. A
+* 404 is that answer even when the lookup just succeeded: these stores are
+* remote and concurrent, so an object can be deleted between resolving its
+* address and fetching it. Reporting that ordinary race as a server failure
+* would make a caller handle an error for something its own contract already
+* has a value for.
+*
+* Anything else THROWS. A dropped connection, a 5xx or a refused request says
+* nothing about whether the object exists, and reporting it as absence invites
+* a caller to treat a live file as deleted and write a replacement over it. The
+* two are easy to state apart and easy to lose when the fetch sits inside the
+* same `try` that catches the lookup.
+*
+* The URL is always one the SERVICE issued, never one assembled from a key.
+* These stores mint addresses carrying suffixes the adapter never chose, so a
+* derived URL is a guess at a string another system owns.
+*
+* @param url - The address the storage service reported for this object
+* @param context - What is being read, for the error message: usually the key
+* @param label - The service's name, so a failure says which store answered
+* @param options - Bounds for the read; see {@link StorageReadOptions}
+* @param signal - A deadline ALREADY RUNNING, covering an earlier phase too
+* @returns The object's bytes, or `null` when the store answers 404
+*/
+async function fetchStoredBytes(url, context, label, options, signal) {
+	let response;
+	try {
+		response = await safeFetch(url, {
+			...options?.maxBytes === void 0 ? {} : { maxResponseBytes: options.maxBytes },
+			...signal !== void 0 ? { signal } : options?.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+		});
+	} catch (error) {
+		const verdict = classifyFetchFailure(error);
+		if (verdict === "absent") return null;
+		if (verdict === "oversized") throw new StorageReadTooLargeError(context, resolveReadBounds(options).maxBytes);
+		throw error;
+	}
+	if (response.status === 404) return null;
+	if (!response.ok) throw NextlyError.internal({ logContext: {
+		service: label,
+		path: context,
+		status: response.status,
+		statusText: response.statusText
+	} });
+	return Buffer.from(await response.arrayBuffer());
+}
+/**
+* What a failed fetch actually says about the object.
+*
+* Its own function because the three answers are the whole point of this module
+* and they are easy to collapse into each other — each collapse having been a
+* real defect here rather than a hypothetical:
+*
+* - ABSENT. A 404 is absence whatever size its body was. `safeFetch` caps while
+*   buffering, so a verbose CDN error page raises before a `Response` exists
+*   and the status check further down is never reached; the object is still
+*   gone, and must not become an error because the page explaining it was long.
+* - OVERSIZED. Only a SUCCESSFUL response that blew the cap. A failed response
+*   can exceed it too, and translating on the reason alone reported a backend
+*   outage as "your file is too big" — a cause the author would act on, wrongly.
+* - UNKNOWN. Everything else, including a too-large refusal carrying NO status:
+*   that means the failure arrived before any status did, which says nothing
+*   about whether the object was oversized.
+*/
+function classifyFetchFailure(error) {
+	if (!(error instanceof SafeFetchError)) return "unknown";
+	if (error.status === 404) return "absent";
+	const successful = error.status !== void 0 && error.status >= 200 && error.status < 300;
+	return error.reason === "response-too-large" && successful ? "oversized" : "unknown";
+}
+/** The deadline a stored read runs under when the caller names none. */
+const DEFAULT_READ_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+/** The byte cap a stored read runs under when the caller names none. */
+const DEFAULT_READ_MAX_BYTES = DEFAULT_MAX_RESPONSE_BYTES;
+/**
+* The bounds a read actually runs under, defaults filled in.
+*
+* ONE place, because every adapter needs the same answer and the ones that
+* derived it themselves diverged: the URL-backed pair inherited `safeFetch`'s
+* cap and deadline for free, while the local and S3 adapters — which never
+* touch `safeFetch` — applied NO bound at all when the caller named none.
+* `StorageReadOptions` promises the default either way, and a production caller
+* reading media without options got it from two of four backends.
+*
+* Filling the defaults here rather than per adapter is what makes the promise
+* true by construction rather than by four implementations agreeing.
+*/
+function resolveReadBounds(options) {
+	return {
+		maxBytes: options?.maxBytes ?? DEFAULT_READ_MAX_BYTES,
+		timeoutMs: options?.timeoutMs ?? DEFAULT_READ_TIMEOUT_MS
+	};
+}
 // src/adapter.ts
+/**
+* Vercel Blob Storage Adapter
+*
+* Stores files on Vercel Blob Storage, a globally distributed object storage
+* service powered by Cloudflare R2. Optimized for Vercel deployments with
+* built-in CDN distribution.
+*
+* Features:
+* - Globally distributed CDN-backed storage
+* - Automatic file management with unique filenames
+* - Token-based authentication
+* - Client-side upload support (via handleUpload API)
+* - Serverless-friendly (no filesystem access required)
+*
+* @example Basic usage
+* ```typescript
+* const adapter = new VercelBlobStorageAdapter({
+*   token: process.env.BLOB_READ_WRITE_TOKEN,
+*   collections: { media: true }
+* });
+*
+* const result = await adapter.upload(buffer, {
+*   filename: 'photo.jpg',
+*   mimeType: 'image/jpeg'
+* });
+* // result.url: "https://abc123.public.blob.vercel-storage.com/photo-xyz.jpg"
+* ```
+*/
+/**
+* Vercel Blob Storage Adapter
+*
+* Implements the IStorageAdapter interface for Vercel Blob Storage.
+* Provides file upload, deletion, existence checks, and metadata retrieval.
+*/
 var VercelBlobStorageAdapter = class {
-  /**
-   * Create a new Vercel Blob storage adapter.
-   *
-   * @param config - Vercel Blob storage configuration
-   * @throws Error if token is not provided
-   */
-  constructor(config) {
-    this.config = config;
-    const token = config.token || process.env.BLOB_READ_WRITE_TOKEN || "";
-    if (!token) {
-      throw new Error(
-        "@nextly/storage-vercel-blob: token is required.\n\nEither set the BLOB_READ_WRITE_TOKEN environment variable or pass token in config.\nGet your token from: Vercel Dashboard > Storage > Blob > Tokens"
-      );
-    }
-    this.resolvedConfig = {
-      token,
-      addRandomSuffix: config.addRandomSuffix ?? true,
-      cacheControlMaxAge: config.cacheControlMaxAge ?? 31536e3,
-      access: config.access ?? "public",
-      storeId: config.storeId,
-      allowOverwrite: config.allowOverwrite ?? false,
-      multipartThreshold: config.multipartThreshold ?? 5 * 1024 * 1024
-      // 5MB
-    };
-  }
-  resolvedConfig;
-  // ============================================================
-  // Core IStorageAdapter Methods
-  // ============================================================
-  /**
-   * Upload file to Vercel Blob.
-   *
-   * Files are stored with globally distributed CDN backing.
-   * By default, a random suffix is added to prevent filename collisions.
-   *
-   * @param buffer - File content as Buffer
-   * @param options - Upload options (filename, mimeType, folder, collection)
-   * @returns Upload result with URL and storage path
-   */
-  async upload(buffer, options) {
-    const mimeType = (options.contentType || options.mimeType || "").toLowerCase().trim();
-    const filename = (options.filename || "").toLowerCase();
-    const ext = filename.includes(".") ? filename.slice(filename.lastIndexOf(".") + 1) : "";
-    const isSvg = mimeType === "image/svg+xml" || ext === "svg" || ext === "svgz";
-    const isHtml = mimeType === "text/html" || mimeType === "application/xhtml+xml" || ext === "html" || ext === "htm" || ext === "xhtml";
-    if (isSvg || isHtml) {
-      const kind = isSvg ? "SVG" : "HTML";
-      throw new Error(
-        `[nextly/storage-vercel-blob] ${kind} uploads are rejected on Vercel Blob \u2014 the platform cannot serve them with attachment-disposition or a restrictive CSP, so they would be stored XSS. Use the S3 / R2 adapter for ${kind} files, or convert to a raster format (PNG/WebP).`
-      );
-    }
-    const pathname = this.buildPathname(options.filename, options.folder);
-    const result = await blob.put(pathname, buffer, {
-      access: this.resolvedConfig.access,
-      token: this.resolvedConfig.token,
-      contentType: options.contentType || options.mimeType,
-      addRandomSuffix: this.resolvedConfig.addRandomSuffix,
-      cacheControlMaxAge: this.resolvedConfig.cacheControlMaxAge
-    });
-    return {
-      url: result.url,
-      path: result.url
-    };
-  }
-  /**
-   * Delete file from Vercel Blob.
-   *
-   * @param filePath - Full blob URL to delete
-   */
-  async delete(filePath) {
-    await blob.del(filePath, {
-      token: this.resolvedConfig.token
-    });
-  }
-  /**
-   * Delete multiple files from Vercel Blob in chunked batches.
-   *
-   * Processes deletions in chunks of 10 concurrent calls using Promise.allSettled,
-   * collecting successes and failures without short-circuiting.
-   *
-   * @param filePaths - Array of full blob URLs to delete
-   * @returns BulkDeleteResult with successful and failed arrays
-   */
-  async bulkDelete(filePaths) {
-    const successful = [];
-    const failed = [];
-    const chunkSize = 10;
-    for (let i = 0; i < filePaths.length; i += chunkSize) {
-      const chunk = filePaths.slice(i, i + chunkSize);
-      const results = await Promise.allSettled(
-        chunk.map((fp) => blob.del(fp, { token: this.resolvedConfig.token }))
-      );
-      results.forEach((result, idx) => {
-        const fp = chunk[idx];
-        if (result.status === "fulfilled") {
-          successful.push(fp);
-        } else {
-          failed.push({
-            filePath: fp,
-            error: result.reason instanceof Error ? result.reason.message : String(result.reason)
-          });
-        }
-      });
-    }
-    return { successful, failed };
-  }
-  /**
-   * Check if file exists in Vercel Blob.
-   *
-   * Uses the head() function which is efficient for existence checks.
-   *
-   * @param filePath - Full blob URL to check
-   * @returns true if file exists, false otherwise
-   */
-  async exists(filePath) {
-    try {
-      await blob.head(filePath, {
-        token: this.resolvedConfig.token
-      });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  /**
-   * Get public URL for Vercel Blob file.
-   *
-   * Vercel Blob paths ARE the public URLs - they're already full HTTPS URLs
-   * with CDN distribution.
-   *
-   * @param filePath - Full blob URL
-   * @returns The same URL (Vercel Blob paths are already public URLs)
-   */
-  getPublicUrl(filePath) {
-    return filePath;
-  }
-  /**
-   * Get storage type identifier.
-   */
-  getType() {
-    return "vercel-blob";
-  }
-  // ============================================================
-  // Optional IStorageAdapter Methods
-  // ============================================================
-  /**
-   * Get adapter info including capabilities.
-   *
-   * @returns Adapter info with type, name, and capability flags
-   */
-  getInfo() {
-    return {
-      type: "vercel-blob",
-      name: "VercelBlobStorageAdapter",
-      supportsSignedUrls: false,
-      // Vercel Blob URLs are public by default
-      supportsClientUploads: true
-      // Via handleUpload API
-    };
-  }
-  /**
-   * Get file metadata from Vercel Blob.
-   *
-   * Retrieves file information including size, content type, and upload date.
-   *
-   * @param filePath - Full blob URL
-   * @returns File metadata or null if file not found
-   */
-  async getMetadata(filePath) {
-    try {
-      const result = await blob.head(filePath, {
-        token: this.resolvedConfig.token
-      });
-      const filename = result.pathname.split("/").pop() || result.pathname;
-      return {
-        id: filePath,
-        filename,
-        originalFilename: filename,
-        mimeType: result.contentType,
-        size: result.size,
-        url: result.url,
-        createdAt: result.uploadedAt.toISOString()
-      };
-    } catch {
-      return null;
-    }
-  }
-  /**
-   * Generate pre-signed URL for client-side uploads.
-   *
-   * Vercel Blob uses a different pattern for client uploads - they require
-   * the handleUpload API which handles token generation server-side.
-   *
-   * This method is not implemented because Vercel Blob's client upload flow
-   * requires server-side route handlers with handleUpload().
-   *
-   * @see https://vercel.com/docs/storage/vercel-blob/client-upload
-   * @throws Error always - client uploads require handleUpload API
-   */
-  getPresignedUploadUrl(_key, _mimeType, _expiresIn) {
-    return Promise.reject(
-      new Error(
-        "@nextly/storage-vercel-blob: Client uploads require the handleUpload API.\n\nVercel Blob uses a different pattern for client-side uploads that involves:\n1. A server-side route handler with handleUpload()\n2. The @vercel/blob/client upload() function\n\nSee: https://vercel.com/docs/storage/vercel-blob/client-upload\n\nFor server-side uploads, use the standard upload() method instead."
-      )
-    );
-  }
-  // ============================================================
-  // Additional Methods
-  // ============================================================
-  /**
-   * List blobs with optional prefix filter.
-   *
-   * Useful for browsing or batch operations on stored files.
-   *
-   * @param prefix - Optional prefix to filter results
-   * @param options - List options (limit, cursor)
-   * @returns List of blob metadata
-   */
-  async listBlobs(prefix, options) {
-    const result = await blob.list({
-      token: this.resolvedConfig.token,
-      prefix,
-      limit: options?.limit,
-      cursor: options?.cursor
-    });
-    return {
-      blobs: result.blobs.map((blob) => ({
-        url: blob.url,
-        pathname: blob.pathname,
-        size: blob.size,
-        uploadedAt: blob.uploadedAt
-      })),
-      hasMore: result.hasMore,
-      cursor: result.cursor
-    };
-  }
-  // ============================================================
-  // Helper Methods
-  // ============================================================
-  /**
-   * Build pathname for Vercel Blob upload.
-   *
-   * Creates pathname in format: {folder}/{filename}
-   * If no folder is provided, uses the filename directly.
-   *
-   * @param filename - Original filename (will be sanitized)
-   * @param folder - Optional folder/prefix for organizing uploads
-   * @returns Generated pathname
-   * @throws Error if folder fails sanitization
-   */
-  buildPathname(filename, folder) {
-    const sanitized = this.sanitizeFilename(filename);
-    if (!folder) return sanitized;
-    return `${this.sanitizeFolder(folder)}/${sanitized}`;
-  }
-  /**
-   * Sanitize filename to prevent path traversal issues.
-   *
-   * @param filename - Original filename
-   * @returns Sanitized filename
-   */
-  sanitizeFilename(filename) {
-    const basename = filename.split(/[/\\]/).pop() || filename;
-    return basename.replace(/[^a-zA-Z0-9._-]/g, "-");
-  }
-  /**
-   * Reject folder values that would let a caller
-   * escape the configured prefix via path traversal or weird
-   * separators. Vercel Blob is flat-keyed so `/` is just part of the
-   * pathname, but an attacker who controls `folder` could still:
-   *
-   *   - Use `..` to chain a relative-traversal-style key.
-   *   - Use `\` (Windows separator) to confuse downstream tooling.
-   *   - Use control chars / null bytes to truncate the key.
-   *   - Use a leading `/` to look like an absolute path.
-   *
-   * Internal `/` segments stay allowed because callers legitimately
-   * use nested folders (`docs/2026/...`); a leading `/`, empty
-   * segments (`docs//x`), or `..` segments are rejected.
-   *
-   * @throws Error with a stable message so the storage facade can
-   *   surface a 400 instead of a 500.
-   */
-  sanitizeFolder(folder) {
-    const trimmed = folder.replace(/\/+$/, "");
-    if (!trimmed) {
-      throw new Error("Folder must be a non-empty string.");
-    }
-    if (/[\\\0\x01-\x1f\x7f]/.test(trimmed)) {
-      throw new Error(
-        "Folder contains forbidden characters (backslash, control chars, or null bytes)."
-      );
-    }
-    if (trimmed.startsWith("/")) {
-      throw new Error("Folder must not start with `/`.");
-    }
-    const segments = trimmed.split("/");
-    for (const segment of segments) {
-      if (segment === "") {
-        throw new Error("Folder must not contain empty segments (`//`).");
-      }
-      if (segment === "..") {
-        throw new Error("Folder must not contain `..` segments.");
-      }
-    }
-    return trimmed;
-  }
-  // ============================================================
-  // Public Accessors
-  // ============================================================
-  /**
-   * Get the configured token (masked for logging).
-   */
-  getTokenMasked() {
-    const token = this.resolvedConfig.token;
-    if (token.length <= 8) return "****";
-    return `${token.slice(0, 4)}...${token.slice(-4)}`;
-  }
-  /**
-   * Check if random suffix is enabled.
-   */
-  hasRandomSuffix() {
-    return this.resolvedConfig.addRandomSuffix;
-  }
-  /**
-   * Get configured cache control max age.
-   */
-  getCacheControlMaxAge() {
-    return this.resolvedConfig.cacheControlMaxAge;
-  }
+	config;
+	resolvedConfig;
+	/**
+	* Create a new Vercel Blob storage adapter.
+	*
+	* @param config - Vercel Blob storage configuration
+	* @throws Error if token is not provided
+	*/
+	constructor(config) {
+		this.config = config;
+		const token = config.token || process.env.BLOB_READ_WRITE_TOKEN || "";
+		if (!token) throw new Error("@nextly/storage-vercel-blob: token is required.\n\nEither set the BLOB_READ_WRITE_TOKEN environment variable or pass token in config.\nGet your token from: Vercel Dashboard > Storage > Blob > Tokens");
+		this.resolvedConfig = {
+			token,
+			addRandomSuffix: config.addRandomSuffix ?? true,
+			cacheControlMaxAge: config.cacheControlMaxAge ?? 31536e3,
+			access: config.access ?? "public",
+			storeId: config.storeId,
+			allowOverwrite: config.allowOverwrite ?? false,
+			multipartThreshold: config.multipartThreshold ?? 5242880
+		};
+	}
+	/**
+	* Upload file to Vercel Blob.
+	*
+	* Files are stored with globally distributed CDN backing.
+	* By default, a random suffix is added to prevent filename collisions.
+	*
+	* @param buffer - File content as Buffer
+	* @param options - Upload options (filename, mimeType, folder, collection)
+	* @returns Upload result with URL and storage path
+	*/
+	async upload(buffer, options) {
+		const mimeType = (options.contentType || options.mimeType || "").toLowerCase().trim();
+		const filename = (options.filename || "").toLowerCase();
+		const ext = filename.includes(".") ? filename.slice(filename.lastIndexOf(".") + 1) : "";
+		if (mimeType === "text/html" || mimeType === "application/xhtml+xml" || ext === "html" || ext === "htm" || ext === "xhtml") throw NextlyError.validation({
+			errors: [{
+				path: "file",
+				code: "UNSUPPORTED_FOR_BACKEND",
+				message: "HTML files cannot be hosted on Vercel Blob. Use the S3 or R2 adapter, or upload as another format."
+			}],
+			logContext: {
+				adapter: "vercel-blob",
+				claimedMimeType: options.mimeType,
+				reason: "vercel-blob-rejects-html",
+				filename: options.filename
+			}
+		});
+		const isSvg = mimeType === "image/svg+xml" || ext === "svg" || ext === "svgz";
+		const pathname = this.buildPathname(options.filename, options.folder);
+		const result = await (0, _vercel_blob.put)(pathname, buffer, {
+			access: this.resolvedConfig.access,
+			token: this.resolvedConfig.token,
+			contentType: options.contentType || options.mimeType,
+			addRandomSuffix: this.resolvedConfig.addRandomSuffix,
+			cacheControlMaxAge: this.resolvedConfig.cacheControlMaxAge
+		});
+		return {
+			url: isSvg && options.contentDisposition === "attachment" ? result.downloadUrl : result.url,
+			path: result.url
+		};
+	}
+	/**
+	* Delete file from Vercel Blob.
+	*
+	* @param filePath - Full blob URL to delete
+	*/
+	async delete(filePath) {
+		await (0, _vercel_blob.del)(filePath, { token: this.resolvedConfig.token });
+	}
+	/**
+	* Delete multiple files from Vercel Blob in chunked batches.
+	*
+	* Processes deletions in chunks of 10 concurrent calls using Promise.allSettled,
+	* collecting successes and failures without short-circuiting.
+	*
+	* @param filePaths - Array of full blob URLs to delete
+	* @returns BulkDeleteResult with successful and failed arrays
+	*/
+	async bulkDelete(filePaths) {
+		const successful = [];
+		const failed = [];
+		const chunkSize = 10;
+		for (let i = 0; i < filePaths.length; i += chunkSize) {
+			const chunk = filePaths.slice(i, i + chunkSize);
+			(await Promise.allSettled(chunk.map((fp) => (0, _vercel_blob.del)(fp, { token: this.resolvedConfig.token })))).forEach((result, idx) => {
+				const fp = chunk[idx];
+				if (result.status === "fulfilled") successful.push(fp);
+				else failed.push({
+					filePath: fp,
+					error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+				});
+			});
+		}
+		return {
+			successful,
+			failed
+		};
+	}
+	/**
+	* Check if file exists in Vercel Blob.
+	*
+	* Uses the head() function which is efficient for existence checks.
+	*
+	* @param filePath - Full blob URL to check
+	* @returns true if file exists, false otherwise
+	*/
+	async exists(filePath) {
+		try {
+			await (0, _vercel_blob.head)(filePath, { token: this.resolvedConfig.token });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Read a stored blob back as bytes, or `null` when it is not there.
+	*
+	* A NETWORK round trip, unlike the local adapter's disk read, because the
+	* bytes live on Vercel's CDN and there is no other way to reach them. That
+	* cost is the reason a caller serving these from its own origin has to cache:
+	* the privacy rule that forces same-origin serving does not also make the
+	* fetch free, and an uncached proxy pays it on every request.
+	*
+	* The URL is taken from `head` rather than assembled from `filePath`,
+	* because a blob's address is issued by the service — it carries a random
+	* suffix this adapter never chose — so deriving one here would be guessing at
+	* a string another system owns.
+	*
+	* `null` for a missing blob rather than a throw, matching {@link exists}.
+	*
+	* @param filePath - Blob path/key
+	* @returns The blob's bytes, or `null` when it does not exist
+	*/
+	async read(filePath, options) {
+		const deadline = AbortSignal.timeout(options?.timeoutMs ?? DEFAULT_READ_TIMEOUT_MS);
+		let target;
+		try {
+			const meta = await (0, _vercel_blob.head)(filePath, {
+				token: this.resolvedConfig.token,
+				abortSignal: deadline
+			});
+			target = meta.downloadUrl ?? meta.url;
+		} catch (error) {
+			if (error instanceof _vercel_blob.BlobNotFoundError) return null;
+			throw error;
+		}
+		return await fetchStoredBytes(target, filePath, "Vercel Blob", options, deadline);
+	}
+	/**
+	* Get public URL for Vercel Blob file.
+	*
+	* Vercel Blob paths ARE the public URLs - they're already full HTTPS URLs
+	* with CDN distribution.
+	*
+	* @param filePath - Full blob URL
+	* @returns The same URL (Vercel Blob paths are already public URLs)
+	*/
+	/**
+	* Every blob in the store, by its URL (which is its stored path here), with
+	* when it was uploaded, a page at a time.
+	*/
+	async *list() {
+		let cursor;
+		do {
+			const page = await this.listBlobs(void 0, { cursor });
+			for (const blob of page.blobs) yield {
+				path: blob.url,
+				lastModified: blob.uploadedAt
+			};
+			cursor = page.hasMore ? page.cursor : void 0;
+		} while (cursor);
+	}
+	getPublicUrl(filePath) {
+		return filePath;
+	}
+	/**
+	* Get storage type identifier.
+	*/
+	getType() {
+		return "vercel-blob";
+	}
+	/**
+	* Get adapter info including capabilities.
+	*
+	* @returns Adapter info with type, name, and capability flags
+	*/
+	getInfo() {
+		return {
+			type: "vercel-blob",
+			name: "VercelBlobStorageAdapter",
+			supportsSignedUrls: false,
+			supportsClientUploads: true
+		};
+	}
+	/**
+	* Get file metadata from Vercel Blob.
+	*
+	* Retrieves file information including size, content type, and upload date.
+	*
+	* @param filePath - Full blob URL
+	* @returns File metadata or null if file not found
+	*/
+	async getMetadata(filePath) {
+		try {
+			const result = await (0, _vercel_blob.head)(filePath, { token: this.resolvedConfig.token });
+			const filename = result.pathname.split("/").pop() || result.pathname;
+			return {
+				id: filePath,
+				filename,
+				originalFilename: filename,
+				mimeType: result.contentType,
+				size: result.size,
+				url: result.url,
+				createdAt: result.uploadedAt.toISOString()
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Generate pre-signed URL for client-side uploads.
+	*
+	* Vercel Blob uses a different pattern for client uploads - they require
+	* the handleUpload API which handles token generation server-side.
+	*
+	* This method is not implemented because Vercel Blob's client upload flow
+	* requires server-side route handlers with handleUpload().
+	*
+	* @see https://vercel.com/docs/storage/vercel-blob/client-upload
+	* @throws Error always - client uploads require handleUpload API
+	*/
+	getPresignedUploadUrl(_key, _mimeType, _expiresIn) {
+		return Promise.reject(/* @__PURE__ */ new Error("@nextly/storage-vercel-blob: Client uploads require the handleUpload API.\n\nVercel Blob uses a different pattern for client-side uploads that involves:\n1. A server-side route handler with handleUpload()\n2. The @vercel/blob/client upload() function\n\nSee: https://vercel.com/docs/storage/vercel-blob/client-upload\n\nFor server-side uploads, use the standard upload() method instead."));
+	}
+	/**
+	* List blobs with optional prefix filter.
+	*
+	* Useful for browsing or batch operations on stored files.
+	*
+	* @param prefix - Optional prefix to filter results
+	* @param options - List options (limit, cursor)
+	* @returns List of blob metadata
+	*/
+	async listBlobs(prefix, options) {
+		const result = await (0, _vercel_blob.list)({
+			token: this.resolvedConfig.token,
+			prefix,
+			limit: options?.limit,
+			cursor: options?.cursor
+		});
+		return {
+			blobs: result.blobs.map((blob) => ({
+				url: blob.url,
+				pathname: blob.pathname,
+				size: blob.size,
+				uploadedAt: blob.uploadedAt
+			})),
+			hasMore: result.hasMore,
+			cursor: result.cursor
+		};
+	}
+	/**
+	* Build pathname for Vercel Blob upload.
+	*
+	* Creates pathname in format: {folder}/{filename}
+	* If no folder is provided, uses the filename directly.
+	*
+	* @param filename - Original filename (will be sanitized)
+	* @param folder - Optional folder/prefix for organizing uploads
+	* @returns Generated pathname
+	* @throws Error if folder fails sanitization
+	*/
+	buildPathname(filename, folder) {
+		const sanitized = this.sanitizeFilename(filename);
+		if (!folder) return sanitized;
+		return `${this.sanitizeFolder(folder)}/${sanitized}`;
+	}
+	/**
+	* Sanitize filename to prevent path traversal issues.
+	*
+	* @param filename - Original filename
+	* @returns Sanitized filename
+	*/
+	sanitizeFilename(filename) {
+		return (filename.split(/[/\\]/).pop() || filename).replace(/[^a-zA-Z0-9._-]/g, "-");
+	}
+	/**
+	* Reject folder values that would let a caller
+	* escape the configured prefix via path traversal or weird
+	* separators. Vercel Blob is flat-keyed so `/` is just part of the
+	* pathname, but an attacker who controls `folder` could still:
+	*
+	*   - Use `..` to chain a relative-traversal-style key.
+	*   - Use `\` (Windows separator) to confuse downstream tooling.
+	*   - Use control chars / null bytes to truncate the key.
+	*   - Use a leading `/` to look like an absolute path.
+	*
+	* Internal `/` segments stay allowed because callers legitimately
+	* use nested folders (`docs/2026/...`); a leading `/`, empty
+	* segments (`docs//x`), or `..` segments are rejected.
+	*
+	* @throws Error with a stable message so the storage facade can
+	*   surface a 400 instead of a 500.
+	*/
+	sanitizeFolder(folder) {
+		const trimmed = folder.replace(/\/+$/, "");
+		if (!trimmed) throw new Error("Folder must be a non-empty string.");
+		if (/[\\\0\x01-\x1f\x7f]/.test(trimmed)) throw new Error("Folder contains forbidden characters (backslash, control chars, or null bytes).");
+		if (trimmed.startsWith("/")) throw new Error("Folder must not start with `/`.");
+		const segments = trimmed.split("/");
+		for (const segment of segments) {
+			if (segment === "") throw new Error("Folder must not contain empty segments (`//`).");
+			if (segment === "..") throw new Error("Folder must not contain `..` segments.");
+		}
+		return trimmed;
+	}
+	/**
+	* Get the configured token (masked for logging).
+	*/
+	getTokenMasked() {
+		const token = this.resolvedConfig.token;
+		if (token.length <= 8) return "****";
+		return `${token.slice(0, 4)}...${token.slice(-4)}`;
+	}
+	/**
+	* Check if random suffix is enabled.
+	*/
+	hasRandomSuffix() {
+		return this.resolvedConfig.addRandomSuffix;
+	}
+	/**
+	* Get configured cache control max age.
+	*/
+	getCacheControlMaxAge() {
+		return this.resolvedConfig.cacheControlMaxAge;
+	}
 };
-
 // src/plugin.ts
+/**
+* Create a Vercel Blob storage plugin for Nextly.
+*
+* This factory function creates a StoragePlugin that can be added to
+* the `storage` array in `nextly.config.ts`. Vercel Blob is optimized
+* for Vercel deployments with:
+*
+* - Global CDN distribution
+* - Simple token-based authentication
+* - Client-side upload support (via handleUpload API)
+* - Automatic file management
+*
+* @param config - Vercel Blob storage configuration
+* @returns A StoragePlugin that MediaStorage can register
+*
+* @throws Error if token is not provided (via adapter)
+*/
 function vercelBlobStorage(config) {
-  if (config.enabled === false) {
-    return {
-      name: "vercel-blob-storage",
-      type: "vercel-blob",
-      collections: {},
-      adapter: null
-    };
-  }
-  const adapter = new VercelBlobStorageAdapter(config);
-  const plugin = {
-    name: "vercel-blob-storage",
-    type: "vercel-blob",
-    collections: config.collections,
-    adapter,
-    /**
-     * Generate upload URL for client-side uploads.
-     *
-     * Note: Vercel Blob uses a different pattern for client uploads.
-     * Instead of pre-signed URLs, it uses the handleUpload() API which
-     * requires server-side route handlers.
-     *
-     * This method throws an error explaining the correct approach.
-     *
-     * @see https://vercel.com/docs/storage/vercel-blob/client-upload
-     */
-    getClientUploadUrl(_filename, _mimeType, _collection) {
-      return Promise.reject(
-        new Error(
-          "@nextly/storage-vercel-blob: Client uploads require the handleUpload API.\n\nVercel Blob uses a different pattern than S3 for client-side uploads:\n\n1. Create a server-side route handler with handleUpload()\n2. Use upload() from @vercel/blob/client on the frontend\n\nSee: https://vercel.com/docs/storage/vercel-blob/client-upload"
-        )
-      );
-    },
-    /**
-     * Get signed download URL for file access.
-     *
-     * Note: Vercel Blob URLs are public by default and do not support
-     * signed/temporary URLs. All uploaded blobs are accessible via their
-     * public URL.
-     *
-     * @param path - Storage path (full blob URL)
-     * @returns The same URL (Vercel Blob URLs are public)
-     */
-    getSignedDownloadUrl(path) {
-      return Promise.resolve(path);
-    }
-  };
-  return plugin;
+	if (config.enabled === false) return {
+		name: "vercel-blob-storage",
+		type: "vercel-blob",
+		collections: {},
+		adapter: null
+	};
+	const adapter = new VercelBlobStorageAdapter(config);
+	return {
+		name: "vercel-blob-storage",
+		type: "vercel-blob",
+		collections: config.collections,
+		adapter,
+		/**
+		* Generate upload URL for client-side uploads.
+		*
+		* Note: Vercel Blob uses a different pattern for client uploads.
+		* Instead of pre-signed URLs, it uses the handleUpload() API which
+		* requires server-side route handlers.
+		*
+		* This method throws an error explaining the correct approach.
+		*
+		* @see https://vercel.com/docs/storage/vercel-blob/client-upload
+		*/
+		getClientUploadUrl(_filename, _mimeType, _collection) {
+			return Promise.reject(/* @__PURE__ */ new Error("@nextly/storage-vercel-blob: Client uploads require the handleUpload API.\n\nVercel Blob uses a different pattern than S3 for client-side uploads:\n\n1. Create a server-side route handler with handleUpload()\n2. Use upload() from @vercel/blob/client on the frontend\n\nSee: https://vercel.com/docs/storage/vercel-blob/client-upload"));
+		},
+		/**
+		* Get signed download URL for file access.
+		*
+		* Note: Vercel Blob URLs are public by default and do not support
+		* signed/temporary URLs. All uploaded blobs are accessible via their
+		* public URL.
+		*
+		* @param path - Storage path (full blob URL)
+		* @returns The same URL (Vercel Blob URLs are public)
+		*/
+		getSignedDownloadUrl(path) {
+			return Promise.resolve(path);
+		}
+	};
 }
-
 // src/index.ts
-var PACKAGE_NAME = "@nextly/storage-vercel-blob";
-var PACKAGE_VERSION = "0.1.0";
-
+const PACKAGE_NAME = "@nextly/storage-vercel-blob";
+const PACKAGE_VERSION = "0.1.0";
 exports.PACKAGE_NAME = PACKAGE_NAME;
 exports.PACKAGE_VERSION = PACKAGE_VERSION;
 exports.VercelBlobStorageAdapter = VercelBlobStorageAdapter;
 exports.vercelBlobStorage = vercelBlobStorage;
-//# sourceMappingURL=index.cjs.map
+
 //# sourceMappingURL=index.cjs.map