@snail-js/api 0.1.27 → 1.0.0

package/dist/decorators/header.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+export declare function Header(record: Record<string, unknown>): ClassDecorator & MethodDecorator;
+//# sourceMappingURL=header.d.ts.map

package/dist/decorators/header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../src/decorators/header.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,GAAG,eAAe,CAIxF"}

package/dist/decorators/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Built-in decorators.
+ *
+ * Everything the request layer exposes as a decorator is re-exported from here,
+ * so `import { Get, Post, Query } from "@snail-js/api"` and
+ * `import { Get, Post, Query } from "@snail-js/api/decorators"` are the same
+ * thing.
+ */
+export { Api } from "./api.js";
+export { Server } from "./server.js";
+export { Delete, Get, Head, Options, Patch, Post, Put, Request, type RequestMethodOptions } from "./methods.js";
+export { Data, HeaderParam, HeaderValue, Params, Query, createParamDecoratorFor, defineParamDescriptor, normalizeParamInput, type ParamDecoratorInput } from "./args.js";
+export { Header } from "./header.js";
+export { DownloadProgress, UploadProgress, type SnailProgressCallback } from "./progress.js";
+export { HttpStream, OnSseError, OnSseOpen, OnWsClose, OnWsError, OnWsMessage, OnWsOpen, Sse, SseEvent, WebSocket, Ws, type SnailSseHandlers, type SnailWsHandlers } from "./stream.js";
+export { createClassDecorator, createMethodDecorator, createParamDecorator, createPropertyDecorator, customMetadataKey, getClassMetadata, getMethodMetadata, getOwnMethodMetadata } from "./custom.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/decorators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EACL,MAAM,EACN,GAAG,EACH,IAAI,EACJ,OAAO,EACP,KAAK,EACL,IAAI,EACJ,GAAG,EACH,OAAO,EACP,KAAK,oBAAoB,EAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,IAAI,EACJ,WAAW,EACX,WAAW,EACX,MAAM,EACN,KAAK,EACL,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,EACnB,KAAK,mBAAmB,EACzB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EACL,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,SAAS,EACT,WAAW,EACX,QAAQ,EACR,GAAG,EACH,QAAQ,EACR,SAAS,EACT,EAAE,EACF,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,UAAU,CAAC"}

package/dist/decorators/methods.d.ts

@@ -0,0 +1,33 @@
+import type { SnailMethodDecoratorOptions, SnailMethodType } from "../typings/api.js";
+/** Options accepted by every request-method decorator. */
+export interface RequestMethodOptions extends SnailMethodDecoratorOptions {
+}
+/**
+ * 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.
+ */
+declare function createRequestMethod(method: SnailMethodType): (path?: string, options?: RequestMethodOptions) => MethodDecorator;
+/** `GET` request. */
+export declare const Get: (path?: string, options?: RequestMethodOptions) => MethodDecorator;
+/** `POST` request. */
+export declare const Post: (path?: string, options?: RequestMethodOptions) => MethodDecorator;
+/** `PUT` request. */
+export declare const Put: (path?: string, options?: RequestMethodOptions) => MethodDecorator;
+/** `DELETE` request. */
+export declare const Delete: (path?: string, options?: RequestMethodOptions) => MethodDecorator;
+/** `PATCH` request. */
+export declare const Patch: (path?: string, options?: RequestMethodOptions) => MethodDecorator;
+/** `HEAD` request. */
+export declare const Head: (path?: string, options?: RequestMethodOptions) => MethodDecorator;
+/** `OPTIONS` request. */
+export declare const Options: (path?: string, options?: RequestMethodOptions) => MethodDecorator;
+/** Alias kept for symmetry with `axios.request` style naming. */
+export declare const Request: typeof createRequestMethod;
+export {};
+//# sourceMappingURL=methods.d.ts.map

package/dist/decorators/methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.d.ts","sourceRoot":"","sources":["../../src/decorators/methods.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,2BAA2B,EAC3B,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAIxB,0DAA0D;AAC1D,MAAM,WAAW,oBAAqB,SAAQ,2BAA2B;CAAG;AAE5E;;;;;;;;;GASG;AACH,iBAAS,mBAAmB,CAAC,MAAM,EAAE,eAAe,6BAGvC,oBAAoB,KAC5B,eAAe,CAkCnB;AAED,qBAAqB;AACrB,eAAO,MAAM,GAAG,4BAtCH,oBAAoB,KAC5B,eAqCwC,CAAC;AAC9C,sBAAsB;AACtB,eAAO,MAAM,IAAI,4BAxCJ,oBAAoB,KAC5B,eAuC0C,CAAC;AAChD,qBAAqB;AACrB,eAAO,MAAM,GAAG,4BA1CH,oBAAoB,KAC5B,eAyCwC,CAAC;AAC9C,wBAAwB;AACxB,eAAO,MAAM,MAAM,4BA5CN,oBAAoB,KAC5B,eA2C8C,CAAC;AACpD,uBAAuB;AACvB,eAAO,MAAM,KAAK,4BA9CL,oBAAoB,KAC5B,eA6C4C,CAAC;AAClD,sBAAsB;AACtB,eAAO,MAAM,IAAI,4BAhDJ,oBAAoB,KAC5B,eA+C0C,CAAC;AAChD,yBAAyB;AACzB,eAAO,MAAM,OAAO,4BAlDP,oBAAoB,KAC5B,eAiDgD,CAAC;AAEtD,iEAAiE;AACjE,eAAO,MAAM,OAAO,4BAAsB,CAAC"}

package/dist/decorators/progress.d.ts

@@ -1,6 +1,24 @@
-import "reflect-metadata";
-import { AxiosProgressEvent } from "axios";
-export declare const UPLOAD_PROGRESS_KEY: unique symbol;
-export declare const UploadProgress: (handler: (progressEvent: AxiosProgressEvent) => void) => (target: any, propertyKey: string) => void;
-export declare const DOWNLOAD_PROGRESS_KEY: unique symbol;
-export declare const DownloadProgress: (handler: (progressEvent: AxiosProgressEvent) => void) => (target: any, propertyKey: string) => void;
+import type { AxiosProgressEvent } from "axios";
+/** Signature of an upload/download progress callback. */
+export type SnailProgressCallback = (event: AxiosProgressEvent) => void;
+/**
+ * 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.
+ */
+export declare function UploadProgress(callback: SnailProgressCallback): MethodDecorator;
+/**
+ * Report download progress for the decorated method.
+ *
+ * @see {@link UploadProgress} for the adapter caveat.
+ */
+export declare function DownloadProgress(callback: SnailProgressCallback): MethodDecorator;
+//# sourceMappingURL=progress.d.ts.map

package/dist/decorators/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/decorators/progress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAOhD,yDAAyD;AACzD,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,qBAAqB,GAAG,eAAe,CAI/E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,eAAe,CAIjF"}

package/dist/decorators/server.d.ts

@@ -1,9 +1,30 @@
-import "reflect-metadata";
-import { SnailOption } from "../typings";
-export declare const SERVER_CONFIG_KEY: unique symbol;
+import type { SnailServerOptions } from "../typings/server.js";
 /**
- * 装饰一个继承Snail 的 class，创建后端交互基本实例
- * @param config @type SnailOption
- * @returns
+ * Declare the options of a server class.
+ *
+ * ```ts
+ * @Server({ baseURL: "/api", timeout: 5000 })
+ * class BackEnd extends SnailServer {}
+ * ```
+ *
+ * The shorthand form is equivalent to `{ baseURL }`:
+ *
+ * ```ts
+ * @Server("/api")
+ * class BackEnd extends SnailServer {}
+ * ```
+ *
+ * Applying `@Server` twice merges the options, and the **outermost decorator
+ * wins** — decorators are evaluated bottom-up, so the one written furthest from
+ * the class is applied last:
+ *
+ * ```ts
+ * @Server({ timeout: 30000 })   // applied last → this timeout wins
+ * @Server({ baseURL: "/api" })
+ * class BackEnd extends SnailServer {}
+ * // → { baseURL: "/api", timeout: 30000 }
+ * ```
  */
-export declare const Server: (config: SnailOption) => (target: any) => void;
+export declare function Server(baseURL: string): ClassDecorator;
+export declare function Server(options: SnailServerOptions): ClassDecorator;
+//# sourceMappingURL=server.d.ts.map

package/dist/decorators/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/decorators/server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAI5D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;AACxD,wBAAgB,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAAC"}

package/dist/decorators/stream.d.ts

@@ -0,0 +1,113 @@
+import type { SnailHttpStreamOptions, SnailSseOptions, SnailWsOptions } from "../typings/stream.js";
+/**
+ * Streaming / realtime decorators.
+ *
+ * Three transports, one idea: the decorated members only *describe* handlers,
+ * and `Service.createSse(...)` / `createWebSocket(...)` / a `@HttpStream` method
+ * turn them into a live connection.
+ */
+/** Handler names recorded for an SSE class. */
+export interface SnailSseHandlers {
+    open: Array<(event: Event) => void>;
+    error: Array<(event: Event) => void>;
+    events: Array<{
+        event: string;
+        handler: (message: unknown) => void;
+    }>;
+}
+/**
+ * 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.
+ */
+export declare function Sse(path: string, options?: SnailSseOptions): ClassDecorator;
+/** Register a handler for the SSE `open` event. */
+export declare function OnSseOpen(): MethodDecorator;
+/** Register a handler for the SSE `error` event. */
+export declare function OnSseError(): MethodDecorator;
+/**
+ * Register a handler for a named SSE event.
+ *
+ * @param event event name; omit for the default `message` event
+ */
+export declare function SseEvent(event?: string): MethodDecorator;
+/** Handler names recorded for a WebSocket class. */
+export interface SnailWsHandlers {
+    open: Array<(event: Event) => void>;
+    message: Array<(event: MessageEvent) => void>;
+    close: Array<(event: CloseEvent) => void>;
+    error: Array<(event: Event) => void>;
+}
+/**
+ * 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" });
+ * ```
+ */
+export declare function WebSocket(path: string, options?: SnailWsOptions): ClassDecorator;
+/** Register a handler for the socket `open` event. */
+export declare function OnWsOpen(): MethodDecorator;
+/** Register a handler for incoming messages. */
+export declare function OnWsMessage(): MethodDecorator;
+/** Register a handler for the socket `close` event. */
+export declare function OnWsClose(): MethodDecorator;
+/** Register a handler for the socket `error` event. */
+export declare function OnWsError(): MethodDecorator;
+/** Short alias for {@link WebSocket}. */
+export declare const Ws: typeof WebSocket;
+/**
+ * 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.
+ */
+export declare function HttpStream(path?: string, options?: SnailHttpStreamOptions): MethodDecorator;
+//# sourceMappingURL=stream.d.ts.map

package/dist/decorators/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/decorators/stream.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EACf,cAAc,EACf,MAAM,mBAAmB,CAAC;AAW3B;;;;;;GAMG;AAIH,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC;IACpC,KAAK,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC;IACrC,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAC,CAAC;CACvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAY/E;AAED,mDAAmD;AACnD,wBAAgB,SAAS,IAAI,eAAe,CAI3C;AAED,oDAAoD;AACpD,wBAAgB,UAAU,IAAI,eAAe,CAI5C;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,SAAY,GAAG,eAAe,CAM3D;AAiCD,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC;IACpC,OAAO,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC,CAAC;IAC9C,KAAK,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC,CAAC;IAC1C,KAAK,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,cAAc,CAYpF;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,IAAI,eAAe,CAE1C;AAED,gDAAgD;AAChD,wBAAgB,WAAW,IAAI,eAAe,CAE7C;AAED,uDAAuD;AACvD,wBAAgB,SAAS,IAAI,eAAe,CAE3C;AAED,uDAAuD;AACvD,wBAAgB,SAAS,IAAI,eAAe,CAE3C;AA8BD,yCAAyC;AACzC,eAAO,MAAM,EAAE,kBAAY,CAAC;AAI5B;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,IAAI,SAAK,EACT,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAYjB"}

package/dist/default/options.d.ts

@@ -0,0 +1,19 @@
+import type { SnailLogLevel, SnailServerOptions } from "../typings/server.js";
+/** Default key names of the assumed backend envelope. */
+export declare const DEFAULT_RESPONSE_KEYS: {
+    readonly code: "code";
+    readonly message: "message";
+    readonly data: "data";
+};
+/** Business codes accepted when no `validateCode` is configured. */
+export declare const DEFAULT_ACCEPTED_CODES: readonly number[];
+/** Fully resolved defaults for `@Server(...)`. */
+export declare const DEFAULT_SERVER_OPTIONS: Required<Pick<SnailServerOptions, "name" | "baseURL" | "timeout" | "codeKey" | "messageKey" | "dataKey" | "logLevel" | "coerceJSONString">>;
+/** Numeric ordering of log levels, so `logLevel` can be compared. */
+export declare const LOG_LEVEL_WEIGHT: Record<SnailLogLevel, number>;
+/** Default options for `@Api(...)`. */
+export declare const DEFAULT_API_OPTIONS: {
+    readonly url: "";
+    readonly name: "";
+};
+//# sourceMappingURL=options.d.ts.map

package/dist/default/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/default/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE3E,yDAAyD;AACzD,eAAO,MAAM,qBAAqB;aAChC,IAAI,EAAE,MAAM;aACZ,OAAO,EAAE,SAAS;aAClB,IAAI,EAAE,MAAM;CACJ,CAAC;AAEX,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAa,CAAC;AAElE,kDAAkD;AAClD,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAC3C,IAAI,CACF,kBAAkB,EAChB,MAAM,GACN,SAAS,GACT,SAAS,GACT,SAAS,GACT,YAAY,GACZ,SAAS,GACT,UAAU,GACV,kBAAkB,CACrB,CAUO,CAAC;AAEX,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAM1D,CAAC;AAEF,uCAAuC;AACvC,eAAO,MAAM,mBAAmB;aAC9B,GAAG,EAAE,EAAE;aACP,IAAI,EAAE,EAAE;CACA,CAAC"}

package/dist/error/base.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Base class of every error `@snail-js/api` throws.
+ *
+ * A stable `code` is attached to each subclass so application code can branch
+ * on `error.code` without importing the class, and so the localization layer can
+ * render a translated message.
+ */
+export declare class SnailError extends Error {
+    /** Machine-readable, stable identifier of this error kind. */
+    readonly code: string;
+    /** The underlying cause, when one exists (usually an `AxiosError`). */
+    readonly cause: unknown;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+    /** `true` for every error originating from this library. */
+    static isSnailError(value: unknown): value is SnailError;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/error/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/error/base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,uEAAuE;IACvE,SAAkB,KAAK,EAAE,OAAO,CAAC;IAEjC,YACE,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,EAUjD;IAED,4DAA4D;IAC5D,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEvD;CACF"}

package/dist/error/decorator.d.ts

@@ -0,0 +1,14 @@
+import { SnailError } from "./base.js";
+/**
+ * Thrown when a decorator is applied incorrectly — two request-method decorators
+ * on one method, a parameter decorator on a constructor, and so on.
+ *
+ * These are programmer errors and always surface eagerly, as early as the
+ * decorated class is evaluated.
+ */
+export declare class SnailDecoratorError extends SnailError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=decorator.d.ts.map

package/dist/error/decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../src/error/decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,EAE7D;CACF"}

package/dist/error/hook.d.ts

@@ -0,0 +1,14 @@
+import { SnailError } from "./base.js";
+/**
+ * Thrown when a plugin lifecycle chain is driven illegally — calling `next()`
+ * twice from one hook, or calling `next()` after the chain already settled.
+ *
+ * This is the Koa `compose` invariant, and it catches a very common plugin bug:
+ * a hook that both `await next()` *and* falls through into a second `next()`.
+ */
+export declare class SnailHookError extends SnailError {
+    /** Lifecycle hook that misbehaved, e.g. `"beforeRequest"`. */
+    readonly hook: string;
+    constructor(hook: string, message: string);
+}
+//# sourceMappingURL=hook.d.ts.map

package/dist/error/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/error/hook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAGxC;CACF"}

package/dist/error/index.d.ts

@@ -0,0 +1,8 @@
+export { SnailError } from "./base.js";
+export { SnailDecoratorError } from "./decorator.js";
+export { SnailHookError } from "./hook.js";
+export { SnailOptionsError } from "./options.js";
+export { SnailPluginError } from "./plugin.js";
+export { SnailHttpError, SnailResponseError } from "./response.js";
+export { SnailCancelledError, SnailRequestError, SnailTimeoutError } from "./request.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/error/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/error/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC"}

package/dist/error/options.d.ts

@@ -0,0 +1,12 @@
+import { SnailError } from "./base.js";
+/**
+ * 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.
+ */
+export declare class SnailOptionsError extends SnailError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=options.d.ts.map

package/dist/error/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/error/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,EAE7D;CACF"}

package/dist/error/plugin.d.ts

@@ -0,0 +1,11 @@
+import { SnailError } from "./base.js";
+/** Thrown for plugin registration, dependency and uninstall failures. */
+export declare class SnailPluginError extends SnailError {
+    /** Name of the plugin the failure belongs to, when known. */
+    readonly pluginName: string | undefined;
+    constructor(message: string, options?: {
+        pluginName?: string;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/error/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/error/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,yEAAyE;AACzE,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAExC,YACE,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,EAIvD;CACF"}

package/dist/error/request.d.ts

@@ -0,0 +1,29 @@
+import { SnailError } from "./base.js";
+/** Thrown when a request never reached the server (DNS, offline, CORS, …). */
+export declare class SnailRequestError extends SnailError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when a request exceeded the configured timeout. */
+export declare class SnailTimeoutError extends SnailError {
+    /** Configured timeout, in milliseconds. */
+    readonly timeout: number | undefined;
+    constructor(message: string, options?: {
+        timeout?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a request is cancelled — by `method.abort()`, by a strategy
+ * discarding a stale request, or by an `AbortSignal` the caller supplied.
+ *
+ * Cancellation is *expected* control flow, not a failure, so strategies
+ * deliberately swallow this error kind.
+ */
+export declare class SnailCancelledError extends SnailError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=request.d.ts.map

package/dist/error/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/error/request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,8EAA8E;AAC9E,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,EAE7D;CACF;AAED,6DAA6D;AAC7D,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,EAG/E;CACF;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,YAAY,OAAO,SAAsB,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,EAE3E;CACF"}

package/dist/error/response.d.ts

@@ -0,0 +1,36 @@
+import { SnailError } from "./base.js";
+/**
+ * Thrown when the backend answered with HTTP success but a business status code
+ * that the configured {@link ServerOptions.validateCode} rule rejected.
+ *
+ * The whole parsed body is preserved on `payload`, so an application error
+ * handler can still read `payload.message` / `payload.data`.
+ */
+export declare class SnailResponseError<T = unknown> extends SnailError {
+    /** Business status code reported by the backend. */
+    readonly businessCode: number | string | undefined;
+    /** Full parsed response body. */
+    readonly payload: T;
+    constructor(message: string, options: {
+        businessCode?: number | string;
+        payload: T;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when the transport failed: non-2xx status, network failure, timeout or
+ * abort. `status` is present only when a response actually came back.
+ */
+export declare class SnailHttpError<T = unknown> extends SnailError {
+    readonly status: number | undefined;
+    readonly statusText: string | undefined;
+    readonly payload: T | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        statusText?: string;
+        payload?: T;
+        cause?: unknown;
+        code?: string;
+    });
+}
+//# sourceMappingURL=response.d.ts.map

package/dist/error/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/error/response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC;;;;;;GAMG;AACH,qBAAa,kBAAkB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,UAAU;IAC7D,oDAAoD;IACpD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAEnD,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAEpB,YACE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAKzE;CACF;AAED;;;GAGG;AACH,qBAAa,cAAc,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,UAAU;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,CAAC;IAEhC,YACE,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,CAAC,CAAC;QACZ,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;KACV,EAMP;CACF"}

package/dist/index.d.ts

@@ -1,11 +1,56 @@
-export * from "./core";
-export { Server } from "./decorators/server";
-export { Api } from "./decorators/api";
-export { Get, Put, Post, Patch, Options, Head, Delete, } from "./decorators/method";
-export { NoCache, HitSource } from "./decorators/cache";
-export { Params, Data, Query } from "./decorators/args";
-export { UseStrategy } from "./decorators/strategy";
-export { Versioning, Version } from "./decorators/versioning";
-export { Sse, SseEvent, OnSseError, OnSseOpen } from "./decorators/sse";
-export * from "./typings";
-export * from "./utils";
+/**
+ * `@snail-js/api` — a decorator-driven, plugin-first HTTP client built on axios.
+ *
+ * ## The two rules
+ *
+ * 1. **The core is always imported from the package root.**
+ *    ```ts
+ *    import { SnailServer, Server, Api, Get, Post, Query, Data, Params } from "@snail-js/api";
+ *    ```
+ * 2. **Optional behaviour is imported on demand.**
+ *    ```ts
+ *    import { Cache, Interceptor, Version, VueAdapter } from "@snail-js/api/plugins";
+ *    import { useRequest, usePagination } from "@snail-js/api/strategies";
+ *    ```
+ *
+ * Keeping the plugin and strategy entry points separate is what lets a bundler
+ * drop the cache, the validators and every framework adapter from an application
+ * that does not use them.
+ *
+ * ## Everything is a plugin
+ *
+ * The core owns three things and nothing else: the metadata decorators write, the
+ * request pipeline, and the plugin lifecycle. Caching, versioning, interceptors,
+ * validation, transformation and the Vue/React adapters are all built on the same
+ * public API a third party gets — see `createPlugin` and `docs/guide/plugin-lifecycle.md`.
+ *
+ * @packageDocumentation
+ */
+export { SnailServer } from "./core/server.js";
+export { SnailMethod } from "./core/method.js";
+export type { SnailCodeErrorEvent, SnailMethodEventMap, SnailMethodInit } from "./core/method.js";
+export { SnailContext } from "./core/context.js";
+export type { SnailContextInit } from "./core/context.js";
+export { PluginManager } from "./core/plugin-manager.js";
+export type { RegisteredPlugin } from "./core/plugin-manager.js";
+export { StateBag } from "./core/state-bag.js";
+export { createLogger } from "./core/logger.js";
+export type { SnailLogger } from "./core/logger.js";
+export { composeChain, createPlugin, definePlugin } from "./core/plugin.js";
+export type { BoundHook, PluginDefinition, PluginHooks, PluginSetupApi } from "./core/plugin.js";
+export { appendMetadata, clearMetadataRegistry, collectMethodKeys, defineMetadata, deleteMetadata, getMetadata, getOwnMetadata, hasMetadata, mergeMetadata, resolveOwner } from "./core/metadata.js";
+export * from "./core/metadata.keys.js";
+export * from "./decorators/index.js";
+export { SnailCancelledError, SnailDecoratorError, SnailError, SnailHookError, SnailHttpError, SnailOptionsError, SnailPluginError, SnailRequestError, SnailResponseError, SnailTimeoutError } from "./error/index.js";
+export { Localization, en, getLocale, languages, localization, registerMessages, setLocale, t, zh } from "./locale/index.js";
+export { DEFAULT_ACCEPTED_CODES, DEFAULT_API_OPTIONS, DEFAULT_RESPONSE_KEYS, DEFAULT_SERVER_OPTIONS, LOG_LEVEL_WEIGHT } from "./default/options.js";
+export { Emitter } from "./utils/emitter.js";
+export type { DeepPartial } from "./utils/index.js";
+export { filenameFromDisposition, triggerBlobDownload, triggerDownload } from "./utils/download.js";
+export type { TriggerDownloadOptions, TriggerDownloadResult } from "./utils/download.js";
+export { buildRequestURL, capitalize, deepMerge, deferred, isAbsoluteURL, isBinaryBody, isBrowser, isDefined, isFunction, isObject, isPlainObject, isPromise, joinURL, omit, omitUndefined, pathParamNames, pick, replacePathParams, shortHash, stableStringify, stripQuery, tryCatch } from "./utils/index.js";
+export { hasParamResolver, paramResolvers, paramSources, registerParamResolver } from "./core/args.js";
+export type { IsRawPayload, ResolvedServerOptions, SnailApiOptions, SnailApiProxy, SnailBuiltinParamSource, SnailCacheHitCallback, SnailCodeErrorCallback, SnailCodeOf, SnailCodeValidator, SnailEnvelope, SnailEnvelopeSchema, SnailErrorCallback, SnailFinishCallback, SnailHookKind, SnailHookName, SnailLogLevel, SnailMessageOf, SnailMeta, SnailMethodDecoratorOptions, SnailMethodMeta, SnailMethodOptions, SnailMethodType, SnailMethodTypeLower, SnailNext, SnailParamDescriptor, SnailParamRecord, SnailParamResolver, SnailParamResolverInput, SnailParamSource, SnailPayloadOf, SnailPlugin, SnailPluginInstallContext, SnailPluginObject, SnailRawPayload, SnailResponseKeys, SnailResult, SnailSendOptions, SnailServerOptions, SnailStateAdapter, SnailStateRef, SnailStrategyCommonOptions, SnailSuccessCallback } from "./typings/index.js";
+export type { SnailConnection, SnailHttpStreamConnection, SnailHttpStreamOptions, SnailReconnectPolicy, SnailSocketConnection, SnailSseConnection, SnailSseEndpoint, SnailSseMessage, SnailSseOptions, SnailWsEndpoint, SnailWsOptions } from "./typings/stream.js";
+export type { SnailLanguage, SnailLocaleInput, SnailMessages } from "./locale/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACzE,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,cAAc,EACf,MAAM,eAAe,CAAC;AAIvB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,WAAW,EACX,cAAc,EACd,WAAW,EACX,aAAa,EACb,YAAY,EACb,MAAM,iBAAiB,CAAC;AACzB,cAAc,sBAAsB,CAAC;AAIrC,cAAc,cAAc,CAAC;AAI7B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAIjB,OAAO,EACL,YAAY,EACZ,EAAE,EACF,SAAS,EACT,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,CAAC,EACD,EAAE,EACH,MAAM,UAAU,CAAC;AAIlB,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,eAAe,EACf,UAAU,EACV,SAAS,EACT,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,aAAa,EACb,SAAS,EACT,OAAO,EACP,IAAI,EACJ,aAAa,EACb,cAAc,EACd,IAAI,EACJ,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,UAAU,EACV,QAAQ,EACT,MAAM,SAAS,CAAC;AAIjB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAIrB,YAAY,EACV,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,aAAa,EACb,cAAc,EACd,SAAS,EACT,2BAA2B,EAC3B,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,yBAAyB,EACzB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,0BAA0B,EAC1B,oBAAoB,EACrB,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,eAAe,EACf,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACf,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}