@snail-js/api 0.1.28 → 1.0.0

package/dist/index.js

@@ -0,0 +1,2034 @@
+import { A as stableStringify, B as SnailError, C as buildRequestURL, D as pathParamNames, E as joinURL, F as isFunction, I as isObject, L as isPlainObject, M as isBinaryBody, N as isBrowser, O as replacePathParams, P as isDefined, R as isPromise, S as en, T as isAbsoluteURL, _ as localization, a as SnailHttpError, b as t, c as finalizeRequestURL, d as paramSources, f as registerParamResolver, g as languages, h as getLocale, i as SnailHookError, j as stripQuery, k as shortHash, l as hasParamResolver, m as Localization, n as createPlugin, o as SnailResponseError, r as definePlugin, s as applyParamDescriptors, t as composeChain, u as paramResolvers, v as registerMessages, w as capitalize, x as zh, y as setLocale, z as SnailDecoratorError } from "./chunks/plugin-D3RDffDG.js";
+import { n as SnailRequestError, r as SnailTimeoutError, t as SnailCancelledError } from "./chunks/request-qeRhihEF.js";
+import { a as omitUndefined, i as omit, n as deferred, o as pick, s as tryCatch, t as deepMerge } from "./chunks/object-Ct0w-h4i.js";
+import { a as readKey, c as DEFAULT_API_OPTIONS, d as LOG_LEVEL_WEIGHT, l as DEFAULT_RESPONSE_KEYS, n as buildResult, r as coerceJSONStringBody, s as DEFAULT_ACCEPTED_CODES, t as assertBusinessCode, u as DEFAULT_SERVER_OPTIONS } from "./chunks/response-D-ubkAFl.js";
+import { A as SNAIL_DOWNLOAD_PROGRESS, B as SNAIL_WS_OPTIONS, C as getMetadata, D as resolveOwner, E as mergeMetadata, F as SNAIL_SERVER_OPTIONS, I as SNAIL_SSE_HANDLERS, L as SNAIL_SSE_OPTIONS, M as SNAIL_HTTP_STREAM, N as SNAIL_PARAMS, O as SNAIL_API_OPTIONS, P as SNAIL_REQUEST_METHOD, R as SNAIL_UPLOAD_PROGRESS, S as deleteMetadata, T as hasMetadata, V as createLogger, _ as SnailPluginError, a as customMetadataKey, b as collectMethodKeys, c as getOwnMethodMetadata, d as HeaderValue, f as Params, g as normalizeParamInput, h as defineParamDescriptor, i as createPropertyDecorator, j as SNAIL_HEADERS, k as SNAIL_CUSTOM_KEY_PREFIX, l as Data, m as createParamDecoratorFor, n as createMethodDecorator, o as getClassMetadata, p as Query, r as createParamDecorator, s as getMethodMetadata, t as createClassDecorator, u as HeaderParam, v as appendMetadata, w as getOwnMetadata, x as defineMetadata, y as clearMetadataRegistry, z as SNAIL_WS_HANDLERS } from "./chunks/custom-UchOSg_s.js";
+import { i as Emitter, n as triggerBlobDownload, r as triggerDownload, t as filenameFromDisposition } from "./chunks/download-lBC7oOTT.js";
+import axios, { AxiosHeaders, isCancel } from "axios";
+//#region src/core/state-bag.ts
+/**
+* Typed key/value bag.
+*
+* Two independent bags ride along every request:
+*
+* - `ctx.state` — **plugin scratch space**. Timers, cache keys, in-flight
+*   promises, tracing ids. Never exposed to the caller.
+* - `ctx.meta` — **caller-visible reactive values** (`data`, `loading`, `error`)
+*   created by the framework adapter's `initMeta` hook.
+*
+* Keeping them separate matters: a plugin writing bookkeeping into `meta` would
+* leak internal state into the object the UI renders.
+*/
+var StateBag = class {
+	constructor() {
+		this.values = /* @__PURE__ */ new Map();
+	}
+	get(key, fallback) {
+		return this.values.has(key) ? this.values.get(key) : fallback;
+	}
+	/** Read a value, throwing when the key is absent. */
+	require(key) {
+		if (!this.values.has(key)) throw new ReferenceError(`[snail] context state "${key}" has not been set`);
+		return this.values.get(key);
+	}
+	/** Write a value. */
+	set(key, value) {
+		this.values.set(key, value);
+		return this;
+	}
+	/** Write a value only when the key is currently absent. */
+	setDefault(key, value) {
+		if (!this.values.has(key)) this.values.set(key, value);
+		return this.values.get(key);
+	}
+	/** `true` when the key was ever set (even to `undefined`). */
+	has(key) {
+		return this.values.has(key);
+	}
+	/** Remove a key. Returns whether it existed. */
+	delete(key) {
+		return this.values.delete(key);
+	}
+	/** Drop everything. */
+	clear() {
+		this.values.clear();
+	}
+	/** Current keys. */
+	keys() {
+		return [...this.values.keys()];
+	}
+	/** Shallow snapshot, handy for logging and assertions. */
+	snapshot() {
+		return Object.fromEntries(this.values);
+	}
+};
+//#endregion
+//#region src/core/context.ts
+/**
+* Per-request context — the single object every plugin hook receives.
+*
+* One context exists per `send()` call, so plugins may store freely in
+* `ctx.state` without worrying about concurrent requests colliding. That is a
+* deliberate fix over the pre-rewrite design, where the "event map" and the
+* request config lived on the long-lived `SnailMethod` instance and two
+* overlapping `send()` calls shared mutable state.
+*/
+var SnailContext = class {
+	constructor(init) {
+		this.state = new StateBag();
+		this.meta = {};
+		this.pathParams = {};
+		this.startedAt = Date.now();
+		this.interrupted = false;
+		this.cacheHit = false;
+		this.server = init.server;
+		this.serverOptions = init.serverOptions;
+		this.apiClass = init.apiClass;
+		this.api = init.api;
+		this.apiName = init.apiName;
+		this.apiOptions = init.apiOptions;
+		this.methodName = init.methodName;
+		this.methodType = init.methodType;
+		this.route = init.route;
+		this.fullName = `${init.serverOptions.name}.${init.apiName}.${init.methodName}`;
+		this.request = init.request;
+		this.descriptors = init.descriptors;
+		this.logger = init.logger;
+	}
+	/** Milliseconds elapsed since `send()` started. */
+	get elapsed() {
+		return (this.finishedAt ?? Date.now()) - this.startedAt;
+	}
+	/**
+	* Stop the request.
+	*
+	* With a `response` argument the network call is skipped entirely and that
+	* response is used instead — this is exactly how a cache hit works. Without
+	* one, the request is abandoned and `send()` rejects with a cancellation error.
+	*/
+	interrupt(response) {
+		this.interrupted = true;
+		if (response) this.response = response;
+	}
+	/** `true` when a plugin short-circuited the request. */
+	get isInterrupted() {
+		return this.interrupted;
+	}
+	/** Record that the current response came from a cache. */
+	markCacheHit() {
+		this.cacheHit = true;
+	}
+	/** `true` when the response was served from a cache. */
+	get isCacheHit() {
+		return this.cacheHit;
+	}
+	/** Replace the current response. */
+	setResponse(response) {
+		this.response = response;
+	}
+	/** Read the current response. */
+	getResponse() {
+		return this.response;
+	}
+	/** Read the current response, throwing when there is none. */
+	requireResponse() {
+		if (!this.response) throw new ReferenceError(`[snail] ${this.fullName} has no response at this point`);
+		return this.response;
+	}
+	/** Replace the request config. */
+	setRequest(request) {
+		this.request = request;
+		this.request.url = this.request.url ?? this.route;
+	}
+	/** Read the request config. */
+	getRequest() {
+		return this.request;
+	}
+	/** Replace the parsed result. */
+	setResult(result) {
+		this.result = result;
+	}
+	/**
+	* Clear everything that belongs to one `send()` while keeping the context
+	* identity, so `meta` — and therefore the caller's reactive handles — survive
+	* a re-send.
+	*/
+	reset(request) {
+		this.state.clear();
+		this.pathParams = {};
+		this.response = void 0;
+		this.error = void 0;
+		this.result = void 0;
+		this.finishedAt = void 0;
+		this.interrupted = false;
+		this.cacheHit = false;
+		this.startedAt = Date.now();
+		this.request = request;
+	}
+	/** Shallow copy of the fields worth logging. */
+	describe() {
+		return {
+			name: this.fullName,
+			method: this.methodType,
+			url: this.request.url,
+			route: this.route,
+			baseURL: this.request.baseURL,
+			params: this.request.params,
+			fromCache: this.cacheHit,
+			elapsed: this.elapsed
+		};
+	}
+};
+//#endregion
+//#region src/core/connection.ts
+/**
+* Attach `Symbol.dispose` / `Symbol.asyncDispose` to a connection.
+*
+* Defined as a helper rather than as two methods on each transport because the
+* symbols are *optional*: `esnext.disposable` is a recent addition, and an engine
+* that lacks them would otherwise end up with a property literally named
+* `"undefined"` if the keys were written inline.
+*
+* The result is that a connection can be released three equivalent ways —
+* `close()`, `using`, or `await using` — with `close()` staying the only one that
+* works everywhere.
+*/
+function withDispose(connection) {
+	const symbols = Symbol;
+	const target = connection;
+	if (typeof symbols.dispose === "symbol") target[symbols.dispose] = () => {
+		connection.close();
+	};
+	if (typeof symbols.asyncDispose === "symbol") target[symbols.asyncDispose] = async () => {
+		connection.close();
+	};
+	return connection;
+}
+//#endregion
+//#region src/core/http-stream.ts
+/**
+* Streaming HTTP response.
+*
+* Uses `fetch` so the response body arrives as a `ReadableStream`, which works
+* in browsers, Node 18+ and workers alike. The connection object is itself
+* async-iterable, so callers write `for await (const chunk of stream)`.
+*/
+function createHttpStream(init) {
+	const { url, options, body, name, logger } = init;
+	const controller = new AbortController();
+	const opened = deferred();
+	const closed = deferred();
+	opened.promise.catch(() => void 0);
+	const decodeText = options.decodeText ?? true;
+	const lineDelimited = options.lineDelimited ?? false;
+	let connected = false;
+	let stopped = false;
+	let iterator;
+	const start = async () => {
+		const method = (options.method ?? "POST").toUpperCase();
+		const hasBody = body !== void 0 && method !== "GET";
+		const response = await fetch(url, {
+			method,
+			headers: {
+				accept: "text/event-stream, application/x-ndjson, text/plain",
+				...hasBody ? { "content-type": "application/json" } : {},
+				...options.headers ?? {},
+				...init.headers ?? {}
+			},
+			body: hasBody ? JSON.stringify(body) : void 0,
+			signal: controller.signal
+		});
+		if (!response.ok) throw new SnailRequestError(t("error.request.failed", name, `stream responded ${response.status} ${response.statusText}`));
+		if (!response.body) throw new SnailRequestError(t("error.request.failed", name, "stream response has no readable body"));
+		connected = true;
+		opened.resolve();
+		return response.body.getReader();
+	};
+	/**
+	* Start the request immediately rather than on first iteration.
+	*
+	* `opened` and `closed` are only useful if the request is already in flight — a
+	* lazily started stream leaves `await connection.opened` pending forever, which
+	* is a trap. Creating the connection *is* the "send" action for a stream.
+	*/
+	const readerPromise = start();
+	readerPromise.catch(() => void 0);
+	const createIterator = () => {
+		const decoder = new TextDecoder("utf-8");
+		let pending = "";
+		let reader;
+		const next = async () => {
+			try {
+				reader ??= await readerPromise;
+				while (true) {
+					if (lineDelimited) {
+						const newlineIndex = pending.indexOf("\n");
+						if (newlineIndex !== -1) {
+							const line = pending.slice(0, newlineIndex);
+							pending = pending.slice(newlineIndex + 1);
+							if (line.trim().length === 0) continue;
+							return {
+								value: line,
+								done: false
+							};
+						}
+					} else if (pending.length > 0) {
+						const chunk = pending;
+						pending = "";
+						return {
+							value: chunk,
+							done: false
+						};
+					}
+					const { done, value } = await reader.read();
+					if (done) {
+						connected = false;
+						stopped = true;
+						closed.resolve();
+						if (pending.length > 0) {
+							const tail = pending;
+							pending = "";
+							return {
+								value: tail,
+								done: false
+							};
+						}
+						return {
+							value: void 0,
+							done: true
+						};
+					}
+					pending += decodeText ? decoder.decode(value, { stream: true }) : String(value);
+				}
+			} catch (error) {
+				connected = false;
+				stopped = true;
+				opened.reject(error);
+				closed.resolve();
+				throw error;
+			}
+		};
+		return {
+			next,
+			return: async () => {
+				stopped = true;
+				connected = false;
+				controller.abort();
+				closed.resolve();
+				return {
+					value: void 0,
+					done: true
+				};
+			}
+		};
+	};
+	const connection = withDispose({
+		get connected() {
+			return connected;
+		},
+		opened: opened.promise,
+		closed: closed.promise,
+		close() {
+			if (stopped) return;
+			stopped = true;
+			connected = false;
+			controller.abort();
+			logger.debug(t("info.sse.close", name));
+			closed.resolve();
+		},
+		[Symbol.asyncIterator]() {
+			iterator ??= createIterator();
+			return iterator;
+		},
+		async text() {
+			let out = "";
+			for await (const chunk of connection) out += chunk;
+			return out;
+		}
+	});
+	return connection;
+}
+//#endregion
+//#region src/core/method.ts
+/**
+* One pending request.
+*
+* Created by calling a proxied api method — `userApi.getUser("1")` — and sent by
+* calling {@link SnailMethod.send}. Nothing hits the network until `send()`.
+*
+* ## Why the context is built once and reset
+*
+* Framework adapters create the caller's reactive handles in their `initMeta`
+* hook. Those handles must survive every re-send, so the context is constructed
+* once and {@link SnailContext.reset} clears only the per-request fields. Calling
+* `userApi.getUser()` twice would produce two independent sets of refs, which is
+* exactly the bug the old `request()`-returns-fresh-state design had.
+*/
+var SnailMethod = class {
+	/**
+	* Caller-visible reactive values created by framework adapters.
+	*
+	* A live view of `context.meta`, so the handles an adapter created in
+	* `initMeta` stay stable across every re-send. Empty when no adapter plugin is
+	* installed.
+	*
+	* `loading` and `error` are typed by the {@link SnailMeta} interface; the
+	* envelope handles are named after the server's configured keys, so augment
+	* `SnailMeta` to type them.
+	*/
+	get meta() {
+		return this.context.meta;
+	}
+	constructor(init, args = []) {
+		this.emitter = new Emitter();
+		this.inFlight = false;
+		this.init = init;
+		this.args = args;
+		this.name = `${init.serverOptions.name}.${init.apiName}.${init.methodName}`;
+		this.methodName = init.methodName;
+		this.methodType = init.methodType;
+		this.route = init.route;
+		this.context = new SnailContext({
+			server: init.server,
+			serverOptions: init.serverOptions,
+			apiClass: init.apiClass,
+			api: init.api,
+			apiName: init.apiName,
+			apiOptions: init.apiOptions,
+			methodName: init.methodName,
+			methodType: init.methodType,
+			route: init.route,
+			request: init.requestConfig(),
+			descriptors: init.descriptors,
+			logger: init.logger
+		});
+		init.pluginManager.runEffectsSync("initMeta", this.context);
+	}
+	/** `true` while a request is in flight. */
+	get pending() {
+		return this.inFlight;
+	}
+	/** Result of the most recent successful request. */
+	get result() {
+		return this.context.result;
+	}
+	/** Error from the most recent failed request. */
+	get error() {
+		return this.context.error;
+	}
+	/** The final axios config of the most recent request. */
+	get request() {
+		return this.context.request;
+	}
+	/**
+	* Send the request.
+	*
+	* Any arguments given here replace the ones captured when the method was
+	* proxied, which is what lets a strategy own one instance and vary the
+	* arguments per call.
+	*
+	* ## One request in flight at a time
+	*
+	* A `SnailMethod` owns exactly one context, and that context is what holds the
+	* caller's reactive handles. Two overlapping `send()` calls would therefore
+	* race over the same `ctx.response`, and the slower response could land in the
+	* state the faster one already reported.
+	*
+	* Starting a second send therefore **aborts the first**, so the previous call
+	* rejects with a `SnailCancelledError` and "latest wins" holds. Callers that
+	* genuinely want two parallel requests should create two instances —
+	* `userApi.getUser("1")` and `userApi.getUser("2")` — which is also what makes
+	* the argument types line up.
+	*/
+	async send(...args) {
+		const callArgs = args.length > 0 ? args : this.args;
+		const ctx = this.begin();
+		this.inFlight = true;
+		ctx.logger.info(t("info.request.start", this.methodType, `${ctx.request.baseURL ?? ""}${this.route}`, this.name));
+		try {
+			await this.init.pluginManager.ready;
+			if (Object.keys(ctx.meta).length === 0) this.init.pluginManager.runEffectsSync("initMeta", ctx);
+			this.init.pluginManager.runEffectsSync("beforeCreate", ctx);
+			applyParamDescriptors(ctx, callArgs);
+			finalizeRequestURL(ctx);
+			await this.init.pluginManager.runChain("beforeRequest", ctx, () => this.dispatch(ctx));
+			if (!ctx.response) throw new SnailCancelledError(t("error.request.cancelled", this.name));
+			await this.init.pluginManager.runChain("afterResponse", ctx);
+			const result = this.finalize(ctx);
+			this.emitter.emit("success", result);
+			return result;
+		} catch (error) {
+			throw await this.fail(ctx, error);
+		} finally {
+			this.inFlight = false;
+			ctx.finishedAt = Date.now();
+			try {
+				await this.init.pluginManager.runEffects("afterRequest", ctx);
+			} catch (cleanupError) {
+				ctx.logger.error(t("error.request.failed", this.name, `afterRequest hook: ${String(cleanupError)}`));
+			}
+			this.emitter.emit("finish", void 0);
+		}
+	}
+	/**
+	* Cancel the in-flight request.
+	*
+	* `send()` rejects with a {@link SnailCancelledError}, which strategies treat
+	* as expected control flow rather than a failure.
+	*/
+	abort(reason) {
+		this.controller?.abort(reason);
+	}
+	/** Subscribe to a successful request. Returns an unsubscribe function. */
+	onSuccess(listener) {
+		return this.emitter.on("success", listener);
+	}
+	/** Subscribe to a failed request. */
+	onError(listener) {
+		return this.emitter.on("error", listener);
+	}
+	/**
+	* Subscribe to a rejected business code.
+	*
+	* Observation only: the request still rejects with a `SnailResponseError`, so
+	* this is the right place to raise a toast, not to recover.
+	*/
+	onCodeError(listener) {
+		return this.emitter.on("codeError", listener);
+	}
+	/** Subscribe to settlement, successful or not. */
+	onFinish(listener) {
+		return this.emitter.on("finish", listener);
+	}
+	/** Subscribe to a response served from a cache. */
+	onHitCache(listener) {
+		return this.emitter.on("cache", listener);
+	}
+	/** Reset the context for a fresh send, superseding any request already in flight. */
+	begin() {
+		const ctx = this.context;
+		this.controller?.abort();
+		this.controller = new AbortController();
+		const config = this.init.requestConfig();
+		config.signal = this.controller.signal;
+		ctx.reset(config);
+		return ctx;
+	}
+	/**
+	* The transport step.
+	*
+	* Runs only when every `beforeRequest` hook called `next()`, i.e. only when the
+	* response has to come from the network. The `afterResponse` chain is *not* here
+	* — see {@link SnailMethod.send} for why it has to run on a cache hit too.
+	*/
+	async dispatch(ctx) {
+		let config = this.init.pluginManager.reduce("requestInterceptor", ctx.request, ctx);
+		ctx.request = config;
+		let response;
+		try {
+			response = await this.init.axios.request(config);
+		} catch (error) {
+			throw this.normalizeTransportError(error);
+		}
+		response = coerceJSONStringBody(response, ctx.serverOptions.coerceJSONString);
+		ctx.setResponse(response);
+		const intercepted = this.init.pluginManager.reduce("responseInterceptor", response, ctx);
+		ctx.setResponse(intercepted);
+	}
+	/** Validate the envelope and assemble the caller-facing result. */
+	finalize(ctx) {
+		const response = ctx.requireResponse();
+		const envelope = response.data;
+		const { codeKey, messageKey, dataKey, validateCode } = ctx.serverOptions;
+		const code = readKey(envelope, codeKey);
+		assertBusinessCode({
+			body: envelope,
+			code,
+			dataKey,
+			validate: validateCode,
+			fullName: this.name,
+			message: t("error.response.code", this.name, String(code))
+		});
+		const result = buildResult({
+			response,
+			envelope,
+			codeKey,
+			messageKey,
+			dataKey,
+			fromCache: ctx.isCacheHit,
+			config: ctx.request
+		});
+		ctx.setResult(result);
+		if (ctx.isCacheHit) this.emitter.emit("cache", void 0);
+		ctx.logger.info(t("info.request.success", this.methodType, `${response.config.baseURL ?? ""}${response.config.url ?? ""}`, this.name, `${Math.round(ctx.elapsed)}ms`));
+		return result;
+	}
+	/** Report a failure through the plugin hooks and the events, then rethrow it. */
+	async fail(ctx, error) {
+		ctx.error = error;
+		try {
+			await this.init.pluginManager.runEffects("onError", ctx, error);
+		} catch (hookError) {
+			ctx.logger.error(t("error.request.failed", this.name, `onError hook: ${String(hookError)}`));
+		}
+		if (error instanceof SnailResponseError) {
+			this.emitter.emit("codeError", {
+				code: error.businessCode,
+				payload: error.payload,
+				error
+			});
+			ctx.logger.warn(t("info.request.codeError", this.methodType, this.route, this.name, String(error.businessCode)));
+		} else {
+			this.emitter.emit("error", error);
+			if (!(error instanceof SnailCancelledError)) ctx.logger.error(t("info.request.error", this.methodType, this.route, this.name, String(error)));
+		}
+		return error;
+	}
+	/**
+	* Turn axios' error vocabulary into ours.
+	*
+	* The rule is: **if the server answered, hand back axios' error unchanged** —
+	* it carries `response.status` and `response.data`, which applications and the
+	* auth strategies both branch on. Only when no response exists at all (DNS
+	* failure, offline, CORS rejection) is there nothing useful to preserve, so
+	* that case becomes a typed {@link SnailHttpError} with the axios error as its
+	* `cause`.
+	*/
+	normalizeTransportError(error) {
+		if (error instanceof SnailCancelledError) return error;
+		const axiosError = error;
+		if (isCancel(error) || axiosError?.code === "ERR_CANCELED") return new SnailCancelledError(t("error.request.cancelled", this.name), { cause: error });
+		if (axiosError?.code === "ECONNABORTED" || axiosError?.code === "ETIMEDOUT") return new SnailTimeoutError(t("error.request.timeout", this.name, String(axiosError.config?.timeout ?? "")), {
+			timeout: axiosError.config?.timeout,
+			cause: error
+		});
+		if (axiosError?.isAxiosError === true && !axiosError.response) return new SnailHttpError(t("error.request.failed", this.name, axiosError.message ?? "network error"), {
+			cause: error,
+			code: "SNAIL_NETWORK_ERROR"
+		});
+		return error;
+	}
+};
+//#endregion
+//#region src/core/plugin-manager.ts
+/** Hook names that traverse the plugin list in the forward direction. */
+var FORWARD_HOOKS = /* @__PURE__ */ new Set([
+	"configureServer",
+	"configureApi",
+	"configureMethod",
+	"initMeta",
+	"beforeCreate",
+	"beforeRequest",
+	"requestInterceptor"
+]);
+/** Hook names that traverse the plugin list in the unwind direction. */
+var UNWIND_HOOKS = /* @__PURE__ */ new Set([
+	"afterResponse",
+	"responseInterceptor",
+	"onError",
+	"afterRequest"
+]);
+/**
+* Per-server plugin registry.
+*
+* ## Why this is not a singleton
+*
+* The pre-rewrite implementation kept one global manager plus a mutable
+* `_server` pointer that every caller had to set with `switchServer()` before
+* `getHooks()`. Any two servers in flight — or simply two interleaved `await`s —
+* silently read the *wrong* server's plugins. Each `SnailServer` now owns its
+* own manager and passes its name in the constructor, so that class of bug is
+* unrepresentable.
+*
+* ## Ordering
+*
+* Plugins sort by `priority` descending, ties broken by registration order.
+*
+* - **Forward hooks** run highest-priority first, so an interceptor (`100`)
+*   installs before the cache (`-100`).
+* - **Unwind hooks** run in the opposite direction, closing the onion: the
+*   plugin closest to the network reacts to the response first.
+*
+* ## Sync registration, async install
+*
+* `register()` is synchronous and returns immediately, so `Service.use(A).use(B)`
+* chains naturally while a `dependsOn` mistake still throws on the spot. The
+* `install` hooks themselves may be async; {@link PluginManager.ready} is awaited
+* once per request, before any plugin hook runs.
+*/
+var PluginManager = class {
+	constructor(serverName, serverOptions) {
+		this.serverName = serverName;
+		this.serverOptions = serverOptions;
+		this.registry = /* @__PURE__ */ new Map();
+		this.order = [];
+		this.installTasks = [];
+		this.sequence = 0;
+	}
+	/** Number of registered plugins. */
+	get size() {
+		return this.registry.size;
+	}
+	/** Resolves once every `install` hook has settled. */
+	get ready() {
+		return Promise.all(this.installTasks).then(() => void 0);
+	}
+	/** `true` when a plugin with this name is registered. */
+	has(name) {
+		return this.registry.has(name);
+	}
+	/** Read one registered plugin. */
+	get(name) {
+		return this.registry.get(name);
+	}
+	/** Registered plugin names in chain order (forward phase). */
+	names() {
+		return this.sorted("forward").map((entry) => entry.name);
+	}
+	/** All registered plugins in chain order (forward phase). */
+	list() {
+		return this.sorted("forward");
+	}
+	/**
+	* Validate and register a plugin. Synchronous by design.
+	*
+	* Throws {@link SnailPluginError} for a nameless plugin, a duplicate name or
+	* an unsatisfied `dependsOn` — all before anything is mutated.
+	*/
+	register(plugin) {
+		if (!plugin || typeof plugin !== "object") throw new SnailPluginError("[snail] use() expects a plugin object");
+		const { name } = plugin;
+		if (typeof name !== "string" || name.length === 0) throw new SnailPluginError("[snail] a plugin must declare a non-empty `name`");
+		if (this.registry.has(name)) throw new SnailPluginError(t("error.options.plugin.exists", name, this.serverName), { pluginName: name });
+		for (const dependency of plugin.dependsOn ?? []) if (!this.registry.has(dependency)) throw new SnailPluginError(t("error.options.plugin.missing", name, dependency), { pluginName: name });
+		this.registry.set(name, {
+			name,
+			priority: Number.isFinite(plugin.priority) ? plugin.priority : 0,
+			index: this.sequence++,
+			instance: plugin
+		});
+		this.order.push(name);
+		if (typeof plugin.install === "function") {
+			const context = {
+				serverName: this.serverName,
+				serverOptions: this.serverOptions,
+				pluginNames: this.names()
+			};
+			let outcome;
+			try {
+				outcome = plugin.install(context, plugin.options);
+			} catch (error) {
+				this.registry.delete(name);
+				this.order.pop();
+				throw new SnailPluginError(`[snail] plugin "${name}" failed to install: ${String(error)}`, {
+					pluginName: name,
+					cause: error
+				});
+			}
+			if (outcome && typeof outcome.then === "function") this.installTasks.push(Promise.resolve(outcome).then(() => void 0, (error) => {
+				throw new SnailPluginError(`[snail] plugin "${name}" failed to install: ${String(error)}`, {
+					pluginName: name,
+					cause: error
+				});
+			}));
+		}
+	}
+	/** Unregister a plugin, running its `uninstall` hook first. */
+	async remove(name) {
+		const entry = this.registry.get(name);
+		if (!entry) throw new SnailPluginError(t("error.options.plugin.notFound", name, this.serverName), { pluginName: name });
+		await entry.instance.uninstall?.({
+			serverName: this.serverName,
+			serverOptions: this.serverOptions,
+			pluginNames: this.names()
+		}, entry.instance.options);
+		this.registry.delete(name);
+		const at = this.order.indexOf(name);
+		if (at !== -1) this.order.splice(at, 1);
+	}
+	/** Remove every plugin, unwinding in reverse registration order. */
+	async clear() {
+		for (const name of [...this.order].reverse()) await this.remove(name);
+	}
+	/**
+	* Sorted plugin list.
+	*
+	* `"forward"` → priority descending (highest first).
+	* `"unwind"` → priority ascending (highest last).
+	*/
+	sorted(direction) {
+		const entries = this.order.map((name) => this.registry.get(name)).filter((entry) => entry !== void 0);
+		entries.sort((a, b) => a.priority === b.priority ? a.index - b.index : b.priority - a.priority);
+		return direction === "forward" ? entries : entries.reverse();
+	}
+	/** Hooks of one name, in the direction that hook traverses. */
+	hooks(hookName) {
+		if (!FORWARD_HOOKS.has(hookName) && !UNWIND_HOOKS.has(hookName)) throw new SnailPluginError(t("error.hook.unknown", hookName));
+		const direction = FORWARD_HOOKS.has(hookName) ? "forward" : "unwind";
+		const bound = [];
+		for (const entry of this.sorted(direction)) {
+			const hook = entry.instance[hookName];
+			if (typeof hook === "function") bound.push({
+				pluginName: entry.name,
+				hook
+			});
+		}
+		return bound;
+	}
+	/** `true` when at least one plugin implements `hookName`. */
+	hasHook(hookName) {
+		for (const name of this.order) if (typeof this.registry.get(name).instance[hookName] === "function") return true;
+		return false;
+	}
+	/**
+	* Run a chain hook over every plugin, then `downstream`.
+	*
+	* A plugin that never calls `next()` stops the chain: `downstream` (for
+	* `beforeRequest`, the HTTP request itself) never runs. That is the mechanism
+	* behind a cache hit.
+	*/
+	async runChain(hookName, ctx, downstream) {
+		const hooks = this.hooks(hookName);
+		if (hooks.length === 0) {
+			await downstream?.();
+			return;
+		}
+		await composeChain(hookName, hooks)(ctx, downstream);
+	}
+	/** Run a non-chain hook over every plugin, sequentially and awaited. */
+	async runEffects(hookName, ...args) {
+		for (const { hook } of this.hooks(hookName)) await hook(...args);
+	}
+	/** Run a non-chain hook synchronously — for constructor-time hooks. */
+	runEffectsSync(hookName, ...args) {
+		for (const { hook } of this.hooks(hookName)) hook(...args);
+	}
+	/**
+	* Fold a value through every plugin's hook.
+	*
+	* Used by `requestInterceptor` / `responseInterceptor`, where each plugin may
+	* return a replacement for the value it received. Returning `undefined` keeps
+	* the previous value.
+	*/
+	reduce(hookName, initial, ...args) {
+		let current = initial;
+		for (const { hook } of this.hooks(hookName)) {
+			const next = hook(current, ...args);
+			if (next !== void 0 && next !== null) current = next;
+		}
+		return current;
+	}
+};
+//#endregion
+//#region src/error/options.ts
+/**
+* Thrown when a required configuration block is missing — a server class
+* without `@Server()`, an api class without `@Api()`, or a value that failed
+* one of the option guards.
+*/
+var SnailOptionsError = class extends SnailError {
+	constructor(message, options = {}) {
+		super(message, {
+			code: "SNAIL_OPTIONS_ERROR",
+			cause: options.cause
+		});
+	}
+};
+//#endregion
+//#region src/core/resolve.ts
+/**
+* Turns raw decorator metadata into concrete, fully-defaulted options.
+*
+* Everything a request needs is resolved *here* rather than spread across the
+* server, the proxy and the method. One place to read, one place to test.
+*/
+/** Read and default the options written by `@Server(...)`. */
+function resolveServerOptions(serverClass, fallbackName) {
+	const declared = getMetadata(SNAIL_SERVER_OPTIONS, serverClass);
+	if (!declared) throw new SnailOptionsError(t("error.options.server.missing", fallbackName));
+	const baseURL = declared.baseURL ?? DEFAULT_SERVER_OPTIONS.baseURL;
+	if (typeof baseURL !== "string" || baseURL.length === 0) throw new SnailOptionsError(t("error.options.server.baseURL"));
+	return {
+		...declared,
+		name: declared.name ?? fallbackName,
+		baseURL,
+		timeout: declared.timeout ?? DEFAULT_SERVER_OPTIONS.timeout,
+		codeKey: declared.codeKey ?? DEFAULT_SERVER_OPTIONS.codeKey,
+		messageKey: declared.messageKey ?? DEFAULT_SERVER_OPTIONS.messageKey,
+		dataKey: declared.dataKey ?? DEFAULT_SERVER_OPTIONS.dataKey,
+		logLevel: declared.logLevel ?? DEFAULT_SERVER_OPTIONS.logLevel,
+		coerceJSONString: declared.coerceJSONString ?? DEFAULT_SERVER_OPTIONS.coerceJSONString
+	};
+}
+/** Read and default the options written by `@Api(...)`. */
+function resolveApiOptions(apiClass, fallbackName) {
+	const declared = getMetadata(SNAIL_API_OPTIONS, apiClass) ?? {};
+	if (declared.url !== void 0 && typeof declared.url !== "string") throw new SnailOptionsError(t("error.options.api.url"));
+	return {
+		url: declared.url ?? "",
+		name: declared.name ?? fallbackName,
+		timeout: declared.timeout,
+		adapter: declared.adapter,
+		responseType: declared.responseType,
+		withCredentials: declared.withCredentials
+	};
+}
+/** Read the full request-method options written by `@Get(path, options)`. */
+function resolveMethodDecoratorOptions(apiClass, methodName) {
+	return getMetadata(SNAIL_REQUEST_METHOD, apiClass, methodName);
+}
+/**
+* Merge the three levels of `@Header(...)` — api class, then method.
+*
+* Method-level headers win, which is the only ordering that lets a single
+* endpoint override a class-wide default.
+*/
+function resolveHeaders(apiClass, methodName) {
+	const apiHeaders = getMetadata(SNAIL_HEADERS, apiClass) ?? {};
+	const methodHeaders = getMetadata(SNAIL_HEADERS, apiClass, methodName) ?? {};
+	return AxiosHeaders.from({
+		...apiHeaders,
+		...methodHeaders
+	});
+}
+/** Progress callbacks written by `@UploadProgress()` / `@DownloadProgress()`. */
+function resolveProgress(apiClass, methodName) {
+	return {
+		onUploadProgress: getMetadata(SNAIL_UPLOAD_PROGRESS, apiClass, methodName),
+		onDownloadProgress: getMetadata(SNAIL_DOWNLOAD_PROGRESS, apiClass, methodName)
+	};
+}
+/** Join the api prefix with a method path. */
+function resolveRoute(apiURL, methodPath) {
+	return buildRequestURL(apiURL, methodPath || "");
+}
+/**
+* Build the axios config a request starts from.
+*
+* Values cascade method → api → server, and only the winner survives. The
+* argument decorators and the plugins refine this further during the pipeline.
+*/ function buildBaseRequestConfig(input) {
+	const { serverOptions, apiOptions, methodOptions, methodType, headers } = input;
+	const merged = AxiosHeaders.concat(headers);
+	for (const [key, value] of Object.entries(serverOptions.headers ?? {})) if (!merged.has(key)) merged.set(key, value);
+	return {
+		url: methodOptions.url,
+		method: methodType.toLowerCase(),
+		baseURL: serverOptions.baseURL,
+		timeout: methodOptions.timeout ?? apiOptions.timeout ?? serverOptions.timeout,
+		responseType: methodOptions.responseType ?? apiOptions.responseType ?? serverOptions.responseType ?? "json",
+		withCredentials: methodOptions.withCredentials ?? apiOptions.withCredentials ?? serverOptions.withCredentials,
+		adapter: methodOptions.adapter ?? apiOptions.adapter ?? serverOptions.adapter,
+		headers: merged,
+		params: {
+			...serverOptions.params ?? {},
+			...methodOptions.params ?? {}
+		},
+		data: methodOptions.data,
+		onUploadProgress: methodOptions.onUploadProgress,
+		onDownloadProgress: methodOptions.onDownloadProgress
+	};
+}
+//#endregion
+//#region src/core/resolve-stream.ts
+var EMPTY_SSE_HANDLERS = {
+	open: [],
+	error: [],
+	events: []
+};
+var EMPTY_WS_HANDLERS = {
+	open: [],
+	message: [],
+	close: [],
+	error: []
+};
+/** Read the `@Sse(...)` options and its registered handlers. */
+function resolveSseEndpoint(streamClass) {
+	const declared = getMetadata(SNAIL_SSE_OPTIONS, streamClass);
+	if (!declared) return void 0;
+	return {
+		url: declared.url ?? "",
+		options: declared,
+		handlers: getMetadata(SNAIL_SSE_HANDLERS, streamClass) ?? EMPTY_SSE_HANDLERS
+	};
+}
+/** Read the `@WebSocket(...)` options and its registered handlers. */
+function resolveWsEndpoint(streamClass) {
+	const declared = getMetadata(SNAIL_WS_OPTIONS, streamClass);
+	if (!declared) return void 0;
+	return {
+		url: declared.url ?? "",
+		options: declared,
+		handlers: getMetadata(SNAIL_WS_HANDLERS, streamClass) ?? EMPTY_WS_HANDLERS
+	};
+}
+/** Read the `@HttpStream(...)` options of one method. */
+function resolveHttpStreamEndpoint(apiClass, methodName) {
+	const declared = getMetadata(SNAIL_HTTP_STREAM, apiClass, methodName);
+	if (!declared) return void 0;
+	return {
+		url: declared.url ?? "",
+		options: declared
+	};
+}
+/**
+* Turn an http(s) `baseURL` into the matching WebSocket origin.
+*
+* `https://api.example.com` → `wss://api.example.com`. A relative `baseURL`
+* (the common browser case) keeps working because `new WebSocket` resolves a
+* relative url against the document base — but the scheme still has to be
+* upgraded explicitly, which is what this does.
+*/
+function toWebSocketURL(url) {
+	if (url.startsWith("https://")) return `wss://${url.slice(8)}`;
+	if (url.startsWith("http://")) return `ws://${url.slice(7)}`;
+	return url;
+}
+/**
+* Bind every SSE handler to the instance that will receive the events.
+*
+* Decorators only ever see the prototype, so the raw functions are stored and
+* bound here — one binding per `open()`, against the instance actually created by
+* `createSse`.
+*/
+function rebindSseHandlers(handlers, instance) {
+	return {
+		open: handlers.open.map((fn) => fn.bind(instance)),
+		error: handlers.error.map((fn) => fn.bind(instance)),
+		events: handlers.events.map((entry) => ({
+			event: entry.event,
+			handler: entry.handler.bind(instance)
+		}))
+	};
+}
+/** Bind every WebSocket handler to the instance. @see rebindSseHandlers */
+function rebindWsHandlers(handlers, instance) {
+	return {
+		open: handlers.open.map((fn) => fn.bind(instance)),
+		message: handlers.message.map((fn) => fn.bind(instance)),
+		close: handlers.close.map((fn) => fn.bind(instance)),
+		error: handlers.error.map((fn) => fn.bind(instance))
+	};
+}
+//#endregion
+//#region src/core/reconnect.ts
+/** Defaults used when a transport enables reconnecting without a policy. */
+var DEFAULT_RECONNECT_POLICY = {
+	retries: 3,
+	delayMs: 1e3,
+	maxDelayMs: 3e4,
+	factor: 2,
+	jitter: true
+};
+/**
+* Normalise the `reconnect` option.
+*
+* Returns `undefined` when reconnecting is switched off, so callers can branch on
+* a single falsy check instead of handling `false | undefined | policy`.
+*/
+function resolveReconnectPolicy(policy) {
+	if (policy === false) return void 0;
+	if (policy === void 0) return { ...DEFAULT_RECONNECT_POLICY };
+	return {
+		...DEFAULT_RECONNECT_POLICY,
+		...policy
+	};
+}
+/**
+* Exponential backoff with optional full jitter.
+*
+* `attempt` is 1-based: `attempt: 1` returns the first delay. The result is
+* always capped by `maxDelayMs`, so a long outage cannot push a retry hours out.
+*/
+function backoffDelay(attempt, policy) {
+	const base = policy.delayMs * Math.pow(policy.factor, Math.max(0, attempt - 1));
+	const capped = Math.min(base, policy.maxDelayMs);
+	if (!policy.jitter) return capped;
+	return Math.max(50, Math.round(Math.random() * capped));
+}
+/** `true` when another attempt is allowed. */
+function canRetry(attempt, policy) {
+	return attempt <= policy.retries;
+}
+//#endregion
+//#region src/core/sse.ts
+/**
+* Server-Sent Events over `fetch`.
+*
+* `EventSource` is deliberately not used: it cannot send request headers, cannot
+* `POST`, cannot be aborted cleanly and reconnects on its own terms. A `fetch`
+* stream reader supports all four, and the parser below is ~50 lines.
+*/
+function createSseConnection(init) {
+	const { url, options, handlers, name, logger } = init;
+	const policy = resolveReconnectPolicy(options.reconnect ?? { retries: 3 });
+	const opened = deferred();
+	const closed = deferred();
+	const controller = new AbortController();
+	opened.promise.catch(() => void 0);
+	let connected = false;
+	let stopped = false;
+	let attempt = 0;
+	let retryHint;
+	let timer;
+	let lastError;
+	/**
+	* Whether the current attempt delivered at least one event.
+	*
+	* This is what separates a healthy connection from a doomed one. A server that
+	* accepts the request, sends events and then closes the stream is behaving
+	* correctly and should reconnect with a fresh retry budget; a server that
+	* accepts and immediately closes without ever sending anything is looping, and
+	* its retry budget must actually run out.
+	*
+	* Resetting the counter as soon as headers arrive — the obvious implementation
+	* — makes the budget meaningless and produces an unbounded hot reconnect loop.
+	*/
+	let sawEvent = false;
+	const messageListeners = /* @__PURE__ */ new Set();
+	const eventListeners = /* @__PURE__ */ new Map();
+	/** Invoke one listener set, keeping a broken listener from killing the stream. */
+	const notify = (listeners, message) => {
+		for (const listener of [...listeners]) try {
+			listener(message);
+		} catch (error) {
+			logger.error(`[snail] ${name} SSE message listener threw`, error);
+		}
+	};
+	const dispatch = (message) => {
+		sawEvent = true;
+		for (const entry of handlers.events) {
+			if (entry.event !== message.event) continue;
+			try {
+				entry.handler(message);
+			} catch (error) {
+				logger.error(`[snail] ${name} SSE handler for "${message.event}" threw`, error);
+			}
+		}
+		notify(messageListeners, message);
+		notify(eventListeners.get(message.event) ?? [], message);
+	};
+	const scheduleReconnect = () => {
+		if (stopped) return;
+		if (!policy || !canRetry(attempt + 1, policy)) {
+			if (!connected) opened.reject(lastError ?? new SnailRequestError(t("error.request.failed", name, `SSE connection failed after ${attempt} attempt(s)`)));
+			stopped = true;
+			closed.resolve();
+			return;
+		}
+		attempt += 1;
+		const delay = retryHint ?? backoffDelay(attempt, policy);
+		retryHint = void 0;
+		timer = setTimeout(() => {
+			run();
+		}, delay);
+	};
+	const run = async () => {
+		if (stopped) return;
+		sawEvent = false;
+		try {
+			const response = await fetch(url, {
+				method: options.method ?? "GET",
+				headers: {
+					accept: "text/event-stream",
+					...options.headers ?? {},
+					...init.headers ?? {}
+				},
+				body: options.method === "POST" && options.data !== void 0 ? JSON.stringify(options.data) : void 0,
+				credentials: options.withCredentials ? "include" : "same-origin",
+				signal: controller.signal
+			});
+			if (!response.ok) throw new SnailRequestError(t("error.request.failed", name, `SSE responded ${response.status} ${response.statusText}`));
+			if (!response.body) throw new SnailRequestError(t("error.request.failed", name, "SSE response has no readable body"));
+			if (!connected) {
+				connected = true;
+				opened.resolve();
+				for (const handler of handlers.open) try {
+					handler(new Event("open"));
+				} catch (error) {
+					logger.error(`[snail] ${name} SSE open handler threw`, error);
+				}
+				logger.info(t("info.sse.open", name));
+			}
+			await readStream(response.body, dispatch, (hint) => {
+				retryHint = hint;
+			});
+			connected = false;
+			lastError = void 0;
+			if (sawEvent) attempt = 0;
+			scheduleReconnect();
+		} catch (error) {
+			if (controller.signal.aborted || stopped) {
+				stopped = true;
+				closed.resolve();
+				return;
+			}
+			lastError = error;
+			for (const handler of handlers.error) try {
+				handler(new Event("error"));
+			} catch (handlerError) {
+				logger.error(`[snail] ${name} SSE error handler threw`, handlerError);
+			}
+			logger.warn(t("error.request.failed", name, `SSE ${String(error)}`));
+			connected = false;
+			scheduleReconnect();
+		}
+	};
+	run();
+	return withDispose({
+		get connected() {
+			return connected;
+		},
+		opened: opened.promise,
+		closed: closed.promise,
+		onMessage(listener) {
+			messageListeners.add(listener);
+			return () => {
+				messageListeners.delete(listener);
+			};
+		},
+		on(event, listener) {
+			let listeners = eventListeners.get(event);
+			if (!listeners) {
+				listeners = /* @__PURE__ */ new Set();
+				eventListeners.set(event, listeners);
+			}
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		close() {
+			if (stopped) return;
+			stopped = true;
+			if (timer) clearTimeout(timer);
+			controller.abort();
+			connected = false;
+			messageListeners.clear();
+			eventListeners.clear();
+			logger.info(t("info.sse.close", name));
+			closed.resolve();
+		}
+	});
+}
+/**
+* Parse an event-stream body.
+*
+* Follows the WHATWG rules that matter in practice: lines are terminated by
+* `\n`, `\r\n` or `\r`; a blank line dispatches the buffered event; `:` starts a
+* comment; a field value keeps everything after the first colon, minus one
+* leading space.
+*/
+async function readStream(body, dispatch, onRetry) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder("utf-8");
+	let buffer = "";
+	let eventName = "message";
+	let dataLines = [];
+	let lastId = "";
+	let sawData = false;
+	const flush = () => {
+		if (!sawData) {
+			eventName = "message";
+			dataLines = [];
+			return;
+		}
+		dispatch({
+			event: eventName || "message",
+			data: dataLines.join("\n"),
+			id: lastId,
+			retry: void 0
+		});
+		eventName = "message";
+		dataLines = [];
+		sawData = false;
+	};
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		let newlineIndex = buffer.search(/\r\n|\r|\n/);
+		while (newlineIndex !== -1) {
+			const line = buffer.slice(0, newlineIndex);
+			const terminatorLength = buffer.startsWith("\r\n", newlineIndex) ? 2 : 1;
+			buffer = buffer.slice(newlineIndex + terminatorLength);
+			newlineIndex = buffer.search(/\r\n|\r|\n/);
+			if (line.length === 0) {
+				flush();
+				continue;
+			}
+			if (line.startsWith(":")) continue;
+			const colon = line.indexOf(":");
+			const field = colon === -1 ? line : line.slice(0, colon);
+			let value = colon === -1 ? "" : line.slice(colon + 1);
+			if (value.startsWith(" ")) value = value.slice(1);
+			switch (field) {
+				case "event":
+					eventName = value;
+					break;
+				case "data":
+					dataLines.push(value);
+					sawData = true;
+					break;
+				case "id":
+					lastId = value;
+					break;
+				case "retry": {
+					const parsed = Number.parseInt(value, 10);
+					if (Number.isFinite(parsed)) onRetry(parsed);
+					break;
+				}
+			}
+		}
+	}
+	flush();
+}
+//#endregion
+//#region src/core/websocket.ts
+/**
+* WebSocket with reconnecting and an outbound queue.
+*
+* Two behaviours the platform socket does not give you, and which every real
+* application ends up writing by hand:
+*
+* - **Reconnect with backoff** — `close` is normal; without a policy the socket
+*   simply stays dead after a blip.
+* - **Send-before-open queueing** — `open()` returns immediately, so a caller
+*   that sends on the next line would otherwise throw `InvalidStateError`.
+*/
+function createWsConnection(init) {
+	const { url, options, handlers, name, logger } = init;
+	const policy = resolveReconnectPolicy(options.reconnect ?? { retries: 3 });
+	const serializer = normalizeSerializer(options.serializer);
+	const queueWhileConnecting = options.queueWhileConnecting ?? true;
+	const opened = deferred();
+	const closed = deferred();
+	opened.promise.catch(() => void 0);
+	let socket;
+	let connected = false;
+	let stopped = false;
+	let attempt = 0;
+	let timer;
+	let queue = [];
+	const emit = (kind, event) => {
+		for (const handler of handlers[kind]) try {
+			handler(event);
+		} catch (error) {
+			logger.error(`[snail] ${name} WS ${kind} handler threw`, error);
+		}
+	};
+	const flush = () => {
+		if (!socket || !connected || queue.length === 0) return;
+		const pending = queue;
+		queue = [];
+		for (const message of pending) socket.send(serializer.serialize(message));
+	};
+	const scheduleReconnect = () => {
+		if (stopped) return;
+		if (!policy || !canRetry(attempt + 1, policy)) {
+			if (!connected) opened.reject(new SnailRequestError(t("error.request.failed", name, `WebSocket failed after ${attempt} attempt(s)`)));
+			stopped = true;
+			closed.resolve();
+			return;
+		}
+		attempt += 1;
+		timer = setTimeout(connect, backoffDelay(attempt, policy));
+	};
+	const connect = () => {
+		if (stopped) return;
+		let ws;
+		try {
+			ws = new WebSocket(url, options.protocols);
+		} catch (error) {
+			logger.warn(t("error.request.failed", name, `WebSocket ${String(error)}`));
+			scheduleReconnect();
+			return;
+		}
+		socket = ws;
+		ws.onopen = (event) => {
+			connected = true;
+			attempt = 0;
+			opened.resolve();
+			emit("open", event);
+			logger.info(t("info.ws.open", name));
+			flush();
+		};
+		ws.onmessage = (event) => {
+			const raw = options.serializer === "text" ? event : deserializeEvent(event, serializer);
+			emit("message", raw);
+		};
+		ws.onerror = (event) => {
+			emit("error", event);
+		};
+		ws.onclose = (event) => {
+			connected = false;
+			emit("close", event);
+			logger.info(t("info.ws.close", name, String(event.code)));
+			if (!stopped) scheduleReconnect();
+		};
+	};
+	connect();
+	return withDispose({
+		get connected() {
+			return connected;
+		},
+		opened: opened.promise,
+		closed: closed.promise,
+		send(data) {
+			if (stopped) throw new SnailRequestError(t("error.request.failed", name, "cannot send on a closed WebSocket"));
+			if (!connected) {
+				if (!queueWhileConnecting) throw new SnailRequestError(t("error.request.failed", name, "WebSocket is not open yet"));
+				queue.push(data);
+				return;
+			}
+			socket.send(serializer.serialize(data));
+		},
+		close() {
+			if (stopped) return;
+			stopped = true;
+			if (timer) clearTimeout(timer);
+			queue = [];
+			connected = false;
+			try {
+				socket?.close(1e3, "client closed");
+			} catch {}
+			closed.resolve();
+		}
+	});
+}
+function normalizeSerializer(input) {
+	if (!input || input === "json") return {
+		serialize: (value) => typeof value === "string" ? value : JSON.stringify(value),
+		deserialize: (raw) => {
+			try {
+				return JSON.parse(raw);
+			} catch {
+				return raw;
+			}
+		}
+	};
+	if (input === "text") return {
+		serialize: (value) => String(value),
+		deserialize: (raw) => raw
+	};
+	return {
+		serialize: (value) => String(input.serialize?.(value) ?? value),
+		deserialize: (raw) => input.deserialize?.(raw) ?? raw
+	};
+}
+/** Decode a `MessageEvent` into a plain value for the handlers. */
+function deserializeEvent(event, serializer) {
+	if (typeof event.data !== "string") return event;
+	const decoded = serializer.deserialize(event.data);
+	return {
+		...event,
+		data: decoded
+	};
+}
+//#endregion
+//#region src/core/server.ts
+/**
+* The server base class.
+*
+* Extend it, decorate the subclass with `@Server(...)` and instantiate once:
+*
+* ```ts
+* @Server({ baseURL: "/api", timeout: 5000 })
+* class BackEnd extends SnailServer {}
+*
+* export const Service = new BackEnd();
+* ```
+*
+* The instance owns an axios instance, a plugin registry and the resolved
+* options. It is created eagerly at module load, so `use()` is synchronous and
+* chainable: `Service.use(A()).use(B())`.
+*/
+var SnailServer = class {
+	constructor() {
+		this.apiCache = /* @__PURE__ */ new WeakMap();
+		const serverClass = this.constructor;
+		this.options = resolveServerOptions(serverClass, serverClass.name);
+		this.name = this.options.name;
+		this.logger = createLogger(this.options.logLevel);
+		this.axios = axios.create();
+		this.pluginManager = new PluginManager(this.name, this.options);
+		for (const { hook } of this.pluginManager.hooks("configureServer")) hook(this.options);
+	}
+	/**
+	* Register a plugin.
+	*
+	* Synchronous and chainable. Validation (name, duplicates, `dependsOn`) throws
+	* immediately; an async `install` hook is awaited once, before the first
+	* request, via the manager's `ready` promise.
+	*/
+	use(plugin) {
+		const instance = typeof plugin === "function" ? plugin() : plugin;
+		this.pluginManager.register(instance);
+		return this;
+	}
+	/** Unregister a plugin by instance or by name. */
+	async remove(plugin) {
+		const name = typeof plugin === "string" ? plugin : plugin?.name;
+		if (!name || !this.pluginManager.has(name)) return false;
+		await this.pluginManager.remove(name);
+		return true;
+	}
+	/** `true` when a plugin with this name is registered. */
+	hasPlugin(name) {
+		return this.pluginManager.has(name);
+	}
+	/** Registered plugin names, in chain order. */
+	get plugins() {
+		return this.pluginManager.names();
+	}
+	/**
+	* Turn a decorated api class into a proxy whose methods build requests.
+	*
+	* ```ts
+	* @Api("/user")
+	* class UserApi {
+	*   @Get("/:id")
+	*   getUser(@Params("id") id: string): Promise<User> { return null!; }
+	* }
+	*
+	* export const userApi = Service.createApi(UserApi);
+	* const method = userApi.getUser("1");  // nothing sent yet
+	* const { data } = await method.send();
+	* ```
+	*
+	* A declared return type — `Promise<User>` above — becomes the payload type,
+	* so `data` is `User` with no explicit generic.
+	*/
+	createApi(apiClass) {
+		const cached = this.apiCache.get(apiClass);
+		if (cached) return cached;
+		const apiOptions = resolveApiOptions(apiClass, apiClass.name);
+		for (const { hook } of this.pluginManager.hooks("configureApi")) hook(apiOptions, apiClass);
+		const instance = new apiClass();
+		const descriptors = /* @__PURE__ */ new Map();
+		const descriptorFor = (methodName) => {
+			if (descriptors.has(methodName)) return descriptors.get(methodName);
+			const resolved = this.resolveMethodDescriptor(apiClass, apiOptions, methodName);
+			descriptors.set(methodName, resolved);
+			return resolved;
+		};
+		const proxied = new Proxy(instance, { get: (target, propertyKey, receiver) => {
+			const value = Reflect.get(target, propertyKey, receiver);
+			if (typeof propertyKey === "symbol" || typeof value !== "function") return value;
+			const descriptor = descriptorFor(String(propertyKey));
+			if (!descriptor) return value;
+			if (descriptor.kind === "stream") return (...args) => this.createHttpStream(apiClass, apiOptions, descriptor, args);
+			return (...args) => this.createMethod(apiClass, target, apiOptions, descriptor, args);
+		} });
+		this.apiCache.set(apiClass, proxied);
+		return proxied;
+	}
+	/**
+	* Turn a class decorated with `@Sse(...)` into an endpoint factory.
+	*
+	* ```ts
+	* @Sse("/events")
+	* class Events { @SseEvent() onMessage(m: SnailSseMessage) {} }
+	*
+	* const events = Service.createSse(Events);
+	* const connection = events.open();
+	* ```
+	*/
+	createSse(sseClass) {
+		const endpoint = resolveSseEndpoint(sseClass);
+		if (!endpoint) throw new SnailDecoratorError(`[snail] ${sseClass.name} is missing the @Sse() decorator`);
+		const instance = new sseClass();
+		return { open: () => createSseConnection({
+			url: buildRequestURL(this.options.baseURL, endpoint.url),
+			options: endpoint.options,
+			handlers: rebindSseHandlers(endpoint.handlers, instance),
+			name: `${this.options.name}.${sseClass.name}`,
+			logger: this.logger
+		}) };
+	}
+	/**
+	* Turn a class decorated with `@WebSocket(...)` into an endpoint factory.
+	*
+	* ```ts
+	* @WebSocket("/ws")
+	* class Chat { @OnWsMessage() incoming(event: MessageEvent) {} }
+	*
+	* const chat = Service.createWebSocket(Chat);
+	* const socket = chat.open();
+	* socket.send({ hello: "world" });
+	* ```
+	*/
+	createWebSocket(wsClass) {
+		const endpoint = resolveWsEndpoint(wsClass);
+		if (!endpoint) throw new SnailDecoratorError(`[snail] ${wsClass.name} is missing the @WebSocket() decorator`);
+		const instance = new wsClass();
+		return { open: () => createWsConnection({
+			url: toWebSocketURL(buildRequestURL(this.options.baseURL, endpoint.url)),
+			options: endpoint.options,
+			handlers: rebindWsHandlers(endpoint.handlers, instance),
+			name: `${this.options.name}.${wsClass.name}`,
+			logger: this.logger
+		}) };
+	}
+	/**
+	* Send a one-off request that is **not** backed by a decorated api class.
+	*
+	* This is an escape hatch, and it is deliberately thin: it awaits plugin
+	* installation and then calls the axios instance directly. **No lifecycle hook
+	* runs** — no `beforeRequest`, no `afterResponse`, no caching, no validation, no
+	* response transformation — and the envelope is *not* unwrapped, so you get the
+	* raw `AxiosResponse` back.
+	*
+	* Prefer a decorated api method for anything that should participate in the
+	* plugin pipeline. Reach for this only for a call that genuinely has no place in
+	* a service definition, such as a health check against a third party.
+	*/
+	async request(config) {
+		await this.pluginManager.ready;
+		const merged = {
+			baseURL: this.options.baseURL,
+			timeout: this.options.timeout,
+			...config
+		};
+		return await this.axios.request(merged);
+	}
+	/** Uninstall every plugin, running their cleanup hooks. */
+	async dispose() {
+		await this.pluginManager.clear();
+	}
+	/** Metadata helper for tooling and tests. */
+	describe() {
+		return {
+			name: this.name,
+			baseURL: this.options.baseURL,
+			timeout: this.options.timeout,
+			codeKey: this.options.codeKey,
+			messageKey: this.options.messageKey,
+			dataKey: this.options.dataKey,
+			logLevel: this.options.logLevel,
+			plugins: this.pluginManager.list().map((entry) => ({
+				name: entry.name,
+				priority: entry.priority
+			}))
+		};
+	}
+	/**
+	* Resolve everything static about one decorated method.
+	*
+	* Called once per method per api class. Returns `null` for a member that is not
+	* a decorated endpoint, which is how an api class may keep plain helpers next to
+	* its requests.
+	*/
+	resolveMethodDescriptor(apiClass, apiOptions, methodName) {
+		const streamEndpoint = resolveHttpStreamEndpoint(apiClass, methodName);
+		if (streamEndpoint) return {
+			kind: "stream",
+			methodName,
+			methodType: (streamEndpoint.options.method ?? "POST").toUpperCase(),
+			route: resolveRoute(apiOptions.url, streamEndpoint.url),
+			streamOptions: streamEndpoint.options,
+			headers: resolveHeaders(apiClass, methodName),
+			descriptors: getMetadata(SNAIL_PARAMS, apiClass, methodName) ?? []
+		};
+		const methodOptions = resolveMethodDecoratorOptions(apiClass, methodName);
+		if (!methodOptions) return null;
+		const methodType = methodOptions.method;
+		const progress = resolveProgress(apiClass, methodName);
+		const headers = resolveHeaders(apiClass, methodName);
+		const route = resolveRoute(apiOptions.url, methodOptions.url ?? "");
+		const resolvedMethodOptions = {
+			...methodOptions,
+			url: route,
+			onUploadProgress: methodOptions.onUploadProgress ?? progress.onUploadProgress,
+			onDownloadProgress: methodOptions.onDownloadProgress ?? progress.onDownloadProgress
+		};
+		for (const { hook } of this.pluginManager.hooks("configureMethod")) hook(resolvedMethodOptions, methodName, apiOptions.name);
+		return {
+			kind: "request",
+			methodName,
+			methodType,
+			route,
+			methodOptions: resolvedMethodOptions,
+			headers,
+			descriptors: getMetadata(SNAIL_PARAMS, apiClass, methodName) ?? []
+		};
+	}
+	/**
+	* Build the stream controller behind an `@HttpStream` method.
+	*
+	* A real context is constructed rather than a look-alike, so the `@Query()` /
+	* `@Data()` / `@HeaderValue()` resolvers behave exactly as they do for a normal
+	* request. The plugin pipeline is deliberately skipped: a byte stream has no
+	* envelope to cache or validate.
+	*/
+	createHttpStream(apiClass, apiOptions, descriptor, args) {
+		const streamOptions = descriptor.streamOptions;
+		const methodOptions = {
+			...streamOptions,
+			url: descriptor.route,
+			method: descriptor.methodType
+		};
+		const config = buildBaseRequestConfig({
+			serverOptions: this.options,
+			apiOptions,
+			methodOptions,
+			methodType: descriptor.methodType,
+			headers: descriptor.headers
+		});
+		config.url = descriptor.route;
+		const ctx = new SnailContext({
+			server: this,
+			serverOptions: this.options,
+			apiClass,
+			api: void 0,
+			apiName: apiOptions.name || apiClass.name,
+			apiOptions,
+			methodName: descriptor.methodName,
+			methodType: descriptor.methodType,
+			route: descriptor.route,
+			request: config,
+			descriptors: descriptor.descriptors,
+			logger: this.logger
+		});
+		applyParamDescriptors(ctx, args);
+		finalizeRequestURL(ctx);
+		const headers = Object.fromEntries(Object.entries(ctx.request.headers.toJSON()).map(([key, value]) => [key, String(value)]));
+		return createHttpStream({
+			url: buildRequestURL(this.options.baseURL, ctx.request.url ?? descriptor.route),
+			options: {
+				...streamOptions,
+				method: descriptor.methodType
+			},
+			body: ctx.request.data,
+			name: ctx.fullName,
+			headers,
+			logger: this.logger
+		});
+	}
+	/** Construct the request object a proxied method call returns. */
+	createMethod(apiClass, api, apiOptions, descriptor, args) {
+		const { methodName, methodType, route, methodOptions, headers, descriptors } = descriptor;
+		return new SnailMethod({
+			server: this,
+			pluginManager: this.pluginManager,
+			axios: this.axios,
+			apiClass,
+			api,
+			apiName: apiOptions.name || apiClass.name,
+			apiOptions,
+			serverOptions: this.options,
+			methodName,
+			methodType,
+			route,
+			methodOptions,
+			descriptors,
+			headers,
+			logger: this.logger,
+			requestConfig: () => buildBaseRequestConfig({
+				serverOptions: this.options,
+				apiOptions,
+				methodOptions,
+				methodType,
+				headers
+			})
+		}, args);
+	}
+};
+//#endregion
+//#region src/decorators/api.ts
+function Api(urlOrOptions) {
+	const options = typeof urlOrOptions === "string" || urlOrOptions === void 0 ? { url: urlOrOptions ?? "" } : urlOrOptions;
+	if (options.url !== void 0 && typeof options.url !== "string") throw new SnailDecoratorError(t("error.options.api.url"));
+	return (target) => {
+		if (typeof target !== "function") throw new SnailDecoratorError(t("error.decorator.class.target", "Api"));
+		const previous = getOwnMetadata(SNAIL_API_OPTIONS, target);
+		defineMetadata(SNAIL_API_OPTIONS, previous ? {
+			...previous,
+			...options
+		} : { ...options }, target);
+	};
+}
+//#endregion
+//#region src/decorators/server.ts
+function Server(baseURLOrOptions) {
+	const options = typeof baseURLOrOptions === "string" ? { baseURL: baseURLOrOptions } : baseURLOrOptions;
+	return (target) => {
+		if (typeof target !== "function") throw new SnailDecoratorError(t("error.decorator.class.target", "Server"));
+		const previous = getOwnMetadata(SNAIL_SERVER_OPTIONS, target);
+		defineMetadata(SNAIL_SERVER_OPTIONS, previous ? {
+			...previous,
+			...options
+		} : { ...options }, target);
+	};
+}
+//#endregion
+//#region src/decorators/methods.ts
+/**
+* Build one request-method decorator.
+*
+* Decorated methods are never executed: `createApi` replaces them with a factory
+* that returns a request object. Their body exists purely to declare the argument
+* and return types, so `return null!` (or nothing at all) is the convention.
+*
+* Applying two request-method decorators to one method is an error and throws
+* while the class is being defined, which is the earliest possible moment.
+*/
+function createRequestMethod(method) {
+	return (path = "", options = {}) => {
+		if (typeof path !== "string") throw new SnailDecoratorError(`@${method} expects its first argument to be a string path`);
+		return (target, propertyKey) => {
+			if (propertyKey === void 0) throw new SnailDecoratorError(`@${method} must decorate a method, not a class or a property`);
+			if (getOwnMetadata(SNAIL_REQUEST_METHOD, target, propertyKey)) throw new SnailDecoratorError(t("error.decorator.method.duplicate", String(propertyKey)));
+			defineMetadata(SNAIL_REQUEST_METHOD, {
+				...options,
+				method,
+				url: path
+			}, target, propertyKey);
+		};
+	};
+}
+/** `GET` request. */
+var Get = createRequestMethod("GET");
+/** `POST` request. */
+var Post = createRequestMethod("POST");
+/** `PUT` request. */
+var Put = createRequestMethod("PUT");
+/** `DELETE` request. */
+var Delete = createRequestMethod("DELETE");
+/** `PATCH` request. */
+var Patch = createRequestMethod("PATCH");
+/** `HEAD` request. */
+var Head = createRequestMethod("HEAD");
+/** `OPTIONS` request. */
+var Options = createRequestMethod("OPTIONS");
+/** Alias kept for symmetry with `axios.request` style naming. */
+var Request = createRequestMethod;
+//#endregion
+//#region src/decorators/header.ts
+/**
+* Static request headers.
+*
+* Works on an api class and on a single method; the two levels merge, with the
+* method winning:
+*
+* ```ts
+* @Api("/user")
+* @Header({ "x-client": "web" })
+* class UserApi {
+*   @Get("/secret")
+*   @Header({ "x-scope": "admin" })
+*   secret() {}
+* }
+* // → x-client: web, x-scope: admin
+* ```
+*
+* For a header whose value comes from an argument, use the `@HeaderValue()`
+* parameter decorator.
+*/
+function Header(record) {
+	return ((target, propertyKey) => {
+		mergeMetadata(SNAIL_HEADERS, record, target, propertyKey);
+	});
+}
+//#endregion
+//#region src/decorators/progress.ts
+/**
+* Report upload progress for the decorated method.
+*
+* ```ts
+* @Post("/upload")
+* @UploadProgress((e) => { if (e.total) bar.value = e.loaded / e.total; })
+* upload(@Data() file: FormData) {}
+* ```
+*
+* Progress events require the `xhr` adapter; axios' `fetch` adapter cannot
+* report them. Set `adapter: "xhr"` on the method or the server when using this
+* decorator in a browser.
+*/
+function UploadProgress(callback) {
+	return (target, propertyKey) => {
+		defineMetadata(SNAIL_UPLOAD_PROGRESS, callback, target, propertyKey);
+	};
+}
+/**
+* Report download progress for the decorated method.
+*
+* @see {@link UploadProgress} for the adapter caveat.
+*/
+function DownloadProgress(callback) {
+	return (target, propertyKey) => {
+		defineMetadata(SNAIL_DOWNLOAD_PROGRESS, callback, target, propertyKey);
+	};
+}
+//#endregion
+//#region src/decorators/stream.ts
+/**
+* Declare a Server-Sent Events endpoint.
+*
+* ```ts
+* @Sse("/events")
+* class Ticker {
+*   @OnSseOpen()
+*   open() { console.log("connected"); }
+*
+*   @OnSseError()
+*   failed(event: Event) { console.warn("lost", event); }
+*
+*   @SseEvent()                       // the default `message` event
+*   message(message: SnailSseMessage) {}
+*
+*   @SseEvent("tick")
+*   tick(message: SnailSseMessage) {}
+* }
+*
+* const ticker = Service.createSse(Ticker);
+* const connection = ticker.open();
+*
+* // Decorate with @SseEvent, or subscribe on the connection itself:
+* const off = connection.on("tick", (message) => console.log(message.data));
+* connection.close();
+* ```
+*
+* The transport is `fetch` + a stream reader rather than `EventSource`: that is
+* what makes request headers, `POST` and `withCredentials` possible, none of which
+* `EventSource` supports.
+*/
+function Sse(path, options = {}) {
+	return (target) => {
+		if (typeof target !== "function") throw new SnailDecoratorError(t("error.decorator.class.target", "Sse"));
+		if (getOwnMetadata(SNAIL_WS_OPTIONS, target)) throw new SnailDecoratorError(t("error.decorator.stream.duplicate", target.name));
+		mergeMetadata(SNAIL_SSE_OPTIONS, {
+			...options,
+			url: path
+		}, target);
+	};
+}
+/** Register a handler for the SSE `open` event. */
+function OnSseOpen() {
+	return (target, propertyKey) => {
+		appendSseHandler(target, propertyKey, (handlers, fn) => handlers.open.push(fn));
+	};
+}
+/** Register a handler for the SSE `error` event. */
+function OnSseError() {
+	return (target, propertyKey) => {
+		appendSseHandler(target, propertyKey, (handlers, fn) => handlers.error.push(fn));
+	};
+}
+/**
+* Register a handler for a named SSE event.
+*
+* @param event event name; omit for the default `message` event
+*/
+function SseEvent(event = "message") {
+	return (target, propertyKey) => {
+		appendSseHandler(target, propertyKey, (handlers, fn) => {
+			handlers.events.push({
+				event,
+				handler: fn
+			});
+		});
+	};
+}
+function appendSseHandler(target, propertyKey, push) {
+	if (propertyKey === void 0) throw new SnailDecoratorError("[snail] SSE handler decorators must be used on methods");
+	const fn = target[propertyKey];
+	if (typeof fn !== "function") throw new SnailDecoratorError(`[snail] @SseEvent/@OnSseOpen/@OnSseError must decorate a method, got "${String(propertyKey)}"`);
+	const handlers = getOwnMetadata(SNAIL_SSE_HANDLERS, target) ?? {
+		open: [],
+		error: [],
+		events: []
+	};
+	push(handlers, fn);
+	defineMetadata(SNAIL_SSE_HANDLERS, handlers, target);
+}
+/**
+* Declare a WebSocket endpoint.
+*
+* ```ts
+* @WebSocket("/ws")
+* class ChatSocket {
+*   @OnWsOpen()   connected() {}
+*   @OnWsMessage() incoming(event: MessageEvent) {}
+*   @OnWsClose()  gone(event: CloseEvent) {}
+*   @OnWsError()  failed(event: Event) {}
+* }
+*
+* const chat = Service.createWebSocket(ChatSocket);
+* const socket = chat.open();
+* socket.send({ hello: "world" });
+* ```
+*/
+function WebSocket$1(path, options = {}) {
+	return (target) => {
+		if (typeof target !== "function") throw new SnailDecoratorError(t("error.decorator.class.target", "WebSocket"));
+		if (getOwnMetadata(SNAIL_SSE_OPTIONS, target)) throw new SnailDecoratorError(t("error.decorator.stream.duplicate", target.name));
+		mergeMetadata(SNAIL_WS_OPTIONS, {
+			...options,
+			url: path
+		}, target);
+	};
+}
+/** Register a handler for the socket `open` event. */
+function OnWsOpen() {
+	return wsHandlerDecorator("open");
+}
+/** Register a handler for incoming messages. */
+function OnWsMessage() {
+	return wsHandlerDecorator("message");
+}
+/** Register a handler for the socket `close` event. */
+function OnWsClose() {
+	return wsHandlerDecorator("close");
+}
+/** Register a handler for the socket `error` event. */
+function OnWsError() {
+	return wsHandlerDecorator("error");
+}
+function wsHandlerDecorator(kind) {
+	return (target, propertyKey) => {
+		if (propertyKey === void 0) throw new SnailDecoratorError("[snail] WebSocket handler decorators must be used on methods");
+		const fn = target[propertyKey];
+		if (typeof fn !== "function") throw new SnailDecoratorError(`[snail] @OnWs* must decorate a method, got "${String(propertyKey)}"`);
+		const handlers = getOwnMetadata(SNAIL_WS_HANDLERS, target) ?? {
+			open: [],
+			message: [],
+			close: [],
+			error: []
+		};
+		handlers[kind].push(fn);
+		defineMetadata(SNAIL_WS_HANDLERS, handlers, target);
+	};
+}
+/** Short alias for {@link WebSocket}. */
+var Ws = WebSocket$1;
+/**
+* Declare a streaming HTTP endpoint.
+*
+* ```ts
+* @Api("/ai")
+* class AiApi {
+*   @HttpStream("/chat", { method: "POST" })
+*   chat(@Data() prompt: { text: string }) {}
+* }
+*
+* const stream = aiApi.chat({ text: "hi" });
+* for await (const chunk of stream.stream()) { render(chunk); }
+* ```
+*
+* Unlike `@Get`/`@Post`, the proxied method returns a stream controller instead
+* of a `SnailMethod`, so no envelope validation happens.
+*/
+function HttpStream(path = "", options = {}) {
+	return (target, propertyKey) => {
+		if (propertyKey === void 0) throw new SnailDecoratorError("[snail] @HttpStream must decorate a method");
+		defineMetadata(SNAIL_HTTP_STREAM, {
+			...options,
+			url: path
+		}, target, propertyKey);
+	};
+}
+//#endregion
+export { Api, DEFAULT_ACCEPTED_CODES, DEFAULT_API_OPTIONS, DEFAULT_RESPONSE_KEYS, DEFAULT_SERVER_OPTIONS, Data, Delete, DownloadProgress, Emitter, Get, Head, Header, HeaderParam, HeaderValue, HttpStream, LOG_LEVEL_WEIGHT, Localization, OnSseError, OnSseOpen, OnWsClose, OnWsError, OnWsMessage, OnWsOpen, Options, Params, Patch, PluginManager, Post, Put, Query, Request, SNAIL_API_OPTIONS, SNAIL_CUSTOM_KEY_PREFIX, SNAIL_DOWNLOAD_PROGRESS, SNAIL_HEADERS, SNAIL_HTTP_STREAM, SNAIL_PARAMS, SNAIL_REQUEST_METHOD, SNAIL_SERVER_OPTIONS, SNAIL_SSE_HANDLERS, SNAIL_SSE_OPTIONS, SNAIL_UPLOAD_PROGRESS, SNAIL_WS_HANDLERS, SNAIL_WS_OPTIONS, Server, SnailCancelledError, SnailContext, SnailDecoratorError, SnailError, SnailHookError, SnailHttpError, SnailMethod, SnailOptionsError, SnailPluginError, SnailRequestError, SnailResponseError, SnailServer, SnailTimeoutError, Sse, SseEvent, StateBag, UploadProgress, WebSocket$1 as WebSocket, Ws, appendMetadata, buildRequestURL, capitalize, clearMetadataRegistry, collectMethodKeys, composeChain, createClassDecorator, createLogger, createMethodDecorator, createParamDecorator, createParamDecoratorFor, createPlugin, createPropertyDecorator, customMetadataKey, deepMerge, deferred, defineMetadata, defineParamDescriptor, definePlugin, deleteMetadata, en, filenameFromDisposition, getClassMetadata, getLocale, getMetadata, getMethodMetadata, getOwnMetadata, getOwnMethodMetadata, hasMetadata, hasParamResolver, isAbsoluteURL, isBinaryBody, isBrowser, isDefined, isFunction, isObject, isPlainObject, isPromise, joinURL, languages, localization, mergeMetadata, normalizeParamInput, omit, omitUndefined, paramResolvers, paramSources, pathParamNames, pick, registerMessages, registerParamResolver, replacePathParams, resolveOwner, setLocale, shortHash, stableStringify, stripQuery, t, triggerBlobDownload, triggerDownload, tryCatch, zh };
+
+//# sourceMappingURL=index.js.map