@snail-js/api 0.1.27 → 1.0.0

package/dist/plugins/transform/decorators.d.ts

@@ -0,0 +1,54 @@
+import type { DtoType, PropertyTypeOptions } from "./type.js";
+/** Metadata slot written by `@PropertyType`. */
+export declare const PROPERTY_TYPE_KEY: symbol;
+/** Metadata slot written by `@ExposeName`. */
+export declare const EXPOSE_NAME_KEY: symbol;
+/**
+ * Choose the DTO a response payload is hydrated into.
+ *
+ * Applies to an api class and to a single method; the method wins, so one
+ * endpoint can answer with a different shape than its siblings.
+ *
+ * ```ts
+ * @Api("/user")
+ * @Transform(UserDto)
+ * class UserApi {
+ *   @Get("/:id")
+ *   getUser(@Params("id") id: string): Promise<UserDto> { return null!; }
+ * }
+ * ```
+ */
+export declare function Transform(dto: DtoType): ClassDecorator & MethodDecorator;
+/**
+ * Declare the runtime type of one DTO property.
+ *
+ * ```ts
+ * class OrderDto {
+ *   @PropertyType(() => UserDto) user!: UserDto;
+ *   @PropertyType(() => ItemDto, { array: true }) items!: ItemDto[];
+ *   @PropertyType(() => Date) createdAt!: Date;
+ * }
+ * ```
+ *
+ * A property without `@PropertyType` is assigned as-is, so primitives, plain
+ * objects and arrays of primitives need no declaration — but they *do* need
+ * something that makes the property known, otherwise the unknown-key rule drops
+ * them.
+ */
+export declare function PropertyType(type: () => unknown, options?: PropertyTypeOptions): PropertyDecorator;
+/**
+ * Read a property from a differently-named JSON key.
+ *
+ * ```ts
+ * class UserDto {
+ *   @ExposeName("user_name") userName!: string;
+ * }
+ * // { "user_name": "ada" } → new UserDto().userName === "ada"
+ * ```
+ *
+ * Excluding a key needs no decorator: undeclared JSON keys are already dropped.
+ */
+export declare function ExposeName(jsonKey: string): PropertyDecorator;
+/** Read the DTO of one method: method first, then the api class. */
+export declare function resolveDto(apiClass: unknown, methodName: string): DtoType | undefined;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/plugins/transform/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../../src/plugins/transform/decorators.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAoB,MAAM,QAAQ,CAAC;AAc7E,gDAAgD;AAChD,eAAO,MAAM,iBAAiB,QAA+C,CAAC;AAE9E,8CAA8C;AAC9C,eAAO,MAAM,eAAe,QAA6C,CAAC;AAE1E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,eAAe,CAUxE;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,OAAO,EACnB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,iBAAiB,CAQnB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAQ7D;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CACxB,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,GAAG,SAAS,CAKrB"}

package/dist/plugins/transform/hydrate.d.ts

@@ -0,0 +1,47 @@
+import type { SnailContext } from "../../core/context.js";
+import type { DtoType } from "./type.js";
+/**
+ * The JSON → class hydration engine.
+ *
+ * Hand-written on purpose: `class-transformer` would be a second runtime
+ * dependency next to axios, and `reflect-metadata` cannot help at all here —
+ * TypeScript 7 never emits `design:type`, so *no* library can discover a property
+ * type without a compiler plugin. The declarations this plugin reads
+ * (`@PropertyType`) are therefore not a workaround but the only runtime source of
+ * truth available.
+ *
+ * ## Model
+ *
+ * ```text
+ * hydrate(raw, DtoClass)
+ *   raw is a primitive / null / too deep → returned unchanged
+ *   raw is an array                     → one instance per item
+ *   DtoClass has static fromJSON        → fromJSON(raw, ctx) wins outright
+ *   otherwise                           → new DtoClass() + declared properties
+ * ```
+ */
+/** Depth used when the caller does not set `maxDepth`. */
+export declare const DEFAULT_MAX_DEPTH = 32;
+/** Options accepted by {@link hydrate}. */
+export interface HydrateOptions {
+    /** Keep JSON keys the DTO does not declare. Defaults to `false`. */
+    keepUnknown?: boolean;
+    /** Maximum object depth to descend. Defaults to {@link DEFAULT_MAX_DEPTH}. */
+    maxDepth?: number;
+    /** Forwarded to a DTO's `static fromJSON(raw, ctx)`. */
+    ctx?: SnailContext;
+}
+/**
+ * Turn a plain JSON payload into an instance of `DtoClass`.
+ *
+ * A primitive, `null`, an unknown class or an over-deep value is returned
+ * unchanged rather than wrapped: the caller asked for a class, but a response that
+ * does not look like one is more useful as-is than as an empty instance.
+ *
+ * ```ts
+ * const user = hydrate(raw, UserDto);
+ * user instanceof UserDto; // true
+ * ```
+ */
+export declare function hydrate<T>(raw: unknown, DtoClass: DtoType<T>, options?: HydrateOptions): T;
+//# sourceMappingURL=hydrate.d.ts.map

package/dist/plugins/transform/hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../../src/plugins/transform/hydrate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAoB,MAAM,QAAQ,CAAC;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,wDAAwD;IACxD,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AA6MD;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,cAAmB,GAC3B,CAAC,CAYH"}

package/dist/plugins/transform/index.d.ts

@@ -0,0 +1,41 @@
+import type { SnailPluginObject } from "../../typings/plugin.js";
+import type { DtoType, TransformOptions } from "./type.js";
+/**
+ * JSON → class transform plugin.
+ *
+ * ```ts
+ * import { Transform, PropertyType, ExposeName } from "@snail-js/api/plugins";
+ *
+ * Service.use(Transform());
+ *
+ * class UserDto {
+ *   @ExposeName("user_name") userName!: string;
+ *   @PropertyType(() => Date) createdAt!: Date;
+ * }
+ *
+ * @Api("/user")
+ * @Transform(UserDto)
+ * class UserApi {
+ *   @Get("/:id")
+ *   getUser(@Params("id") id: string): Promise<UserDto> { return null!; }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * The transform plugin factory, and — called with a DTO class — the DTO decorator.
+ *
+ * Two things share one name because the specification gives both of them the name
+ * `Transform`: the factory (`Service.use(Transform())`) and the decorator
+ * (`@Transform(UserDto)`). They are told apart by their argument — a DTO is a
+ * constructor function with no options of its own, options are never callable —
+ * so neither call style has to be renamed.
+ */
+export declare function Transform(dto: DtoType): ClassDecorator & MethodDecorator;
+export declare function Transform(options?: TransformOptions): SnailPluginObject<TransformOptions>;
+export { ExposeName, PropertyType } from "./decorators.js";
+export { hydrate } from "./hydrate.js";
+export type { HydrateOptions } from "./hydrate.js";
+export type { DtoType, PropertyTypeOptions, PropertyTypeSpec, TransformOptions } from "./type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/transform/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/transform/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,eAAe,CAAC;AAC1E,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;AAO3F,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EACV,OAAO,EACP,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,QAAQ,CAAC"}

package/dist/plugins/transform/plugin.d.ts

@@ -0,0 +1,20 @@
+import type { TransformOptions } from "./type.js";
+/**
+ * Create the transform plugin.
+ *
+ * ```ts
+ * Service.use(Transform());
+ *
+ * @Api("/user")
+ * @Transform(UserDto)
+ * class UserApi {
+ *   @Get("/:id")
+ *   getUser(@Params("id") id: string): Promise<UserDto> { return null!; }
+ * }
+ * ```
+ *
+ * Without a DTO — no decorator and no `dto` option — the plugin is a no-op and the
+ * payload stays the plain object JSON.parse produced.
+ */
+export declare const transformPlugin: import("../../index.js").SnailPlugin<TransformOptions>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/transform/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/transform/plugin.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAW,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAqExD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,+CAmB1B,CAAC"}

package/dist/plugins/transform/type.d.ts

@@ -0,0 +1,67 @@
+import type { SnailContext } from "../../core/context.js";
+/**
+ * JSON → class transform types.
+ *
+ * Everything here is deliberately hand-rolled: no `class-transformer`, no
+ * `reflect-metadata`, no design-time type emission. TypeScript 7 cannot emit
+ * constructor parameter types at all, so the plugin relies on the explicit
+ * `@PropertyType()` declarations the DTO author writes — which is also the only
+ * way nested types are visible at runtime without a compiler plugin.
+ */
+/**
+ * A class the transform plugin can hydrate into.
+ *
+ * `fromJSON` is optional and hand-written: when a DTO declares it, it wins over
+ * automatic hydration, because a class that knows how to build itself from JSON
+ * is the authority on its own invariants.
+ */
+export type DtoType<T = unknown> = (new () => T) & {
+    /** Hand-written factory. Receives the raw JSON value and the live context. */
+    fromJSON?: (raw: unknown, ctx?: SnailContext) => T;
+};
+/** Options for one `@PropertyType()` application. */
+export interface PropertyTypeOptions {
+    /**
+     * Hydrate an array of `type` instead of a single value.
+     *
+     * Explicit rather than inferred: an empty JSON array cannot tell the plugin
+     * whether it holds DTOs or primitives, so guessing would produce `[]` either
+     * way while hiding the mistake.
+     */
+    array?: boolean;
+}
+/** What a `@PropertyType()` decorator stores for one property. */
+export interface PropertyTypeSpec {
+    /**
+     * Lazy type resolver, e.g. `() => ChildDto`.
+     *
+     * Lazy is required, not cosmetic: two DTOs that reference each other would
+     * otherwise hit a temporal dead zone at class-definition time.
+     */
+    type: () => unknown;
+    /** Extra options, when the decorator was given any. */
+    options?: PropertyTypeOptions;
+}
+/** Options accepted by the `Transform` plugin factory. */
+export interface TransformOptions {
+    /** DTO used when neither the method nor the api class declares one. */
+    dto?: DtoType;
+    /**
+     * Keep JSON keys the DTO does not declare.
+     *
+     * Defaults to `false`: a DTO is a whitelist, and carrying undeclared keys onto
+     * the instance is how internal backend fields leak into templates. A DTO that
+     * declares *nothing* is the exception — there is no whitelist to apply, so every
+     * own key of the JSON is assigned.
+     */
+    keepUnknown?: boolean;
+    /**
+     * Maximum object depth to descend.
+     *
+     * Defaults to `32`. A self-referencing `@PropertyType` plus deeply nested (or
+     * cyclic) JSON would otherwise recurse until the stack blew, taking the whole
+     * request with it.
+     */
+    maxDepth?: number;
+}
+//# sourceMappingURL=type.d.ts.map

package/dist/plugins/transform/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/plugins/transform/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG;IACjD,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,YAAY,KAAK,CAAC,CAAC;CACpD,CAAC;AAEF,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC;IAEpB,uDAAuD;IACvD,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,GAAG,CAAC,EAAE,OAAO,CAAC;IAEd;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/plugins/validate/decorators.d.ts

@@ -0,0 +1,24 @@
+import type { ZodType } from "zod";
+/**
+ * Validate the outgoing request body (or query) against a zod schema.
+ *
+ * ```ts
+ * @Post("/")
+ * @Validate(z.object({ name: z.string().min(1) }))
+ * create(@Data() body: CreateUser): Promise<User> { return null!; }
+ * ```
+ */
+export declare function Validate(schema: ZodType): ClassDecorator & MethodDecorator;
+/**
+ * Validate the response payload against a zod schema.
+ *
+ * Response validation only ever warns: the backend, not the caller, decides what
+ * it sends, and throwing away a usable payload because one field is unexpected
+ * turns a cosmetic backend drift into a broken page.
+ */
+export declare function ValidateResponse(schema: ZodType): ClassDecorator & MethodDecorator;
+/** Read the request schema of one method: method first, then the api class. */
+export declare function resolveRequestSchema(apiClass: unknown, methodName: string): ZodType | undefined;
+/** Read the response schema of one method: method first, then the api class. */
+export declare function resolveResponseSchema(apiClass: unknown, methodName: string): ZodType | undefined;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/plugins/validate/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../../src/plugins/validate/decorators.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AA6CnC;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,eAAe,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,eAAe,CAElF;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,GAAG,SAAS,CAKrB;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,GAAG,SAAS,CAKrB"}

package/dist/plugins/validate/index.d.ts

@@ -0,0 +1,40 @@
+import type { ZodType } from "zod";
+import type { SnailPluginObject } from "../../typings/plugin.js";
+import type { ValidateOptions } from "./type.js";
+/**
+ * Zod validation plugin.
+ *
+ * ```ts
+ * import { Validate, ValidateResponse } from "@snail-js/api/plugins";
+ *
+ * Service.use(Validate());
+ *
+ * @Api("/user")
+ * class UserApi {
+ *   @Post("/")
+ *   @Validate(z.object({ name: z.string().min(1) }))
+ *   @ValidateResponse(z.object({ id: z.number() }))
+ *   create(@Data() body: CreateUser): Promise<User> { return null!; }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * The validate plugin factory, and — called with a zod schema — the request
+ * schema decorator.
+ *
+ * Two things share one name because the brief that specifies this plugin gives
+ * both of them the name `Validate`: the factory (`Service.use(Validate())`) and
+ * the decorator (`@Validate(schema)`). Rather than rename one of them and break
+ * one of the two call styles, the two are told apart by their argument: a zod
+ * schema is an object with `safeParse`, options never have one. `Validate()` and
+ * `Validate({ request: schema })` return the plugin, `@Validate(schema)` returns
+ * the decorator.
+ */
+export declare function Validate(schema: ZodType): ClassDecorator & MethodDecorator;
+export declare function Validate(options?: ValidateOptions): SnailPluginObject<ValidateOptions>;
+export { ValidateResponse } from "./decorators.js";
+export { SnailValidationError } from "./type.js";
+export type { SnailValidationIssue, ValidateOptions } from "./type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/validate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/validate/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,eAAe,CAAC;AAC5E,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,iBAAiB,CAAC,eAAe,CAAC,CAAC;AAcxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC"}

package/dist/plugins/validate/plugin.d.ts

@@ -0,0 +1,13 @@
+import type { ValidateOptions } from "./type.js";
+/**
+ * Create the zod validation plugin.
+ *
+ * ```ts
+ * Service.use(Validate({ strict: false }));
+ * ```
+ *
+ * It is normally used without options, together with the decorators:
+ * `Service.use(Validate())`.
+ */
+export declare const validatePlugin: import("../../index.js").SnailPlugin<ValidateOptions>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/validate/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/validate/plugin.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAyF9C;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,8CAyBzB,CAAC"}

package/dist/plugins/validate/type.d.ts

@@ -0,0 +1,54 @@
+import type { ZodType, core } from "zod";
+import { SnailError } from "../../error/base.js";
+/**
+ * Zod validation plugin types.
+ *
+ * `zod` is an optional peer dependency and this directory is the only place in the
+ * library allowed to reference it. Everything here is a *type* reference, so
+ * importing the plugin never pulls zod's runtime into the bundle: the schemas are
+ * supplied by the application, which already has zod.
+ */
+/**
+ * One problem zod reported.
+ *
+ * Re-exported under a library-owned name so application code can type an error
+ * handler without importing zod's internal `core` namespace — the deprecation
+ * churn of that namespace should not reach callers through this library.
+ */
+export type SnailValidationIssue = core.$ZodIssue;
+/** Options accepted by the `Validate` plugin factory. */
+export interface ValidateOptions {
+    /** Schema applied when no `@Validate()` decorator declares one. */
+    request?: ZodType;
+    /** Schema applied when no `@ValidateResponse()` decorator declares one. */
+    response?: ZodType;
+    /**
+     * Whether an invalid *request* aborts the call.
+     *
+     * Defaults to `true`. `false` downgrades the failure to a warning and lets the
+     * request go out — useful while developing against a backend whose contract is
+     * still moving, and never a good idea in production. Responses are never
+     * validated strictly.
+     */
+    strict?: boolean;
+}
+/**
+ * Thrown when the request payload does not satisfy its schema.
+ *
+ * The request is abandoned **before** anything reaches the network, which is the
+ * whole point of validating a request: an invalid body that is still sent produces
+ * a backend error that looks like a server bug, and a `4xx` that pollutes the
+ * application's error handling for what is really a programmer mistake.
+ *
+ * `issues` is zod's own list, kept verbatim so the application can render field
+ * paths and messages instead of parsing a string.
+ */
+export declare class SnailValidationError extends SnailError {
+    /** Every issue zod reported, in zod's original shape. */
+    readonly issues: readonly SnailValidationIssue[];
+    constructor(message: string, options: {
+        issues: readonly SnailValidationIssue[];
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=type.d.ts.map

package/dist/plugins/validate/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/plugins/validate/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,SAAS,CAAC;AAElD,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAEjD,YACE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAItE;CACF"}

package/dist/plugins/version/decorators.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Declare the version of an api class or of a single request method.
+ *
+ * ```ts
+ * @Api("/user")
+ * @Version("1.2.0")
+ * class UserApi {
+ *   @Get("/legacy")
+ *   @Version("0.9.0")
+ *   legacy(): Promise<void> { return null!; }
+ * }
+ * ```
+ */
+export declare function Version(version: string): ClassDecorator & MethodDecorator;
+/**
+ * Read the version declared for one method.
+ *
+ * Reads the method slot first, then the class slot, and both walk the prototype
+ * chain so a subclass inherits the version of its base api class.
+ */
+export declare function resolveDeclaredVersion(apiClass: unknown, methodName: string): string | undefined;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/plugins/version/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../../src/plugins/version/decorators.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,eAAe,CAUzE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAKpB"}

package/dist/plugins/version/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Version management plugin.
+ *
+ * ```ts
+ * import { Version, Versioning } from "@snail-js/api/plugins";
+ *
+ * Service.use(Versioning({ type: "url", defaultVersion: "1.0.0" }));
+ *
+ * @Api("/user")
+ * @Version("1.2.0")
+ * class UserApi {
+ *   @Get("/:id")
+ *   getUser(@Params("id") id: string): Promise<User> { return null!; }
+ * }
+ * // → GET /api/v1.2.0/user/1
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { Version } from "./decorators.js";
+export { Versioning } from "./plugin.js";
+export type { VersioningOptions, VersioningPatch, VersioningType } from "./type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/version/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/version/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC"}

package/dist/plugins/version/plugin.d.ts

@@ -0,0 +1,13 @@
+import type { VersioningOptions } from "./type.js";
+/**
+ * Create the version management plugin.
+ *
+ * ```ts
+ * Service.use(Versioning({ type: "url", defaultVersion: "1.0.0" }));
+ * ```
+ *
+ * The rewrite happens in `beforeRequest`, so it is the last thing that can change
+ * the url before the request is hashed, cached and sent.
+ */
+export declare const Versioning: import("../../index.js").SnailPlugin<VersioningOptions>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/version/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/version/plugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAmC,MAAM,QAAQ,CAAC;AAsMjF;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,gDAcrB,CAAC"}

package/dist/plugins/version/type.d.ts

@@ -0,0 +1,47 @@
+import type { SnailContext } from "../../core/context.js";
+/**
+ * Where the versioning plugin writes the version on the outgoing request.
+ *
+ * `"custom"` exists because no fixed list of transports covers every backend:
+ * some gateways want `Accept: application/vnd.acme.v2+json`, some want the
+ * version inside the body. A custom extractor receives the live context and
+ * returns the patch to merge instead of guessing.
+ */
+export type VersioningType = "url" | "header" | "query" | "custom";
+/**
+ * The change a `custom` extractor asks for.
+ *
+ * Every field is optional: an extractor that only touches headers must not be
+ * forced to restate the url it read from `ctx.request`.
+ */
+export interface VersioningPatch {
+    /** Replacement for the request url, used verbatim. */
+    url?: string;
+    /** Headers to merge into the outgoing request. */
+    headers?: Record<string, string>;
+    /** Query params to merge into the outgoing request. */
+    params?: Record<string, unknown>;
+}
+/** Options accepted by the `Versioning` plugin factory. */
+export interface VersioningOptions {
+    /** Transport the version travels on. */
+    type: VersioningType;
+    /**
+     * Version used when neither the method nor the api class declares one.
+     *
+     * Required on purpose: a default version is a contract with the backend, and
+     * silently assuming `"1.0.0"` produces 404s that look like routing bugs.
+     */
+    defaultVersion: string;
+    /**
+     * Key or url segment name.
+     *
+     * Defaults to `"v"` for `url`/`query` (so `/user/1` becomes `/v1.2.0/user/1`)
+     * and to `"x-api-version"` for `header`. Pass `""` in `url` mode for a bare
+     * `/1.2.0/user/1` segment.
+     */
+    key?: string;
+    /** Only for `type: "custom"`. Receives the resolved version and the live context. */
+    extractor?: (version: string, ctx: SnailContext) => VersioningPatch | void;
+}
+//# sourceMappingURL=type.d.ts.map

package/dist/plugins/version/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/plugins/version/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,IAAI,EAAE,cAAc,CAAC;IAErB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,qFAAqF;IACrF,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,KAAK,eAAe,GAAG,IAAI,CAAC;CAC5E"}

package/dist/plugins/vue/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Vue adapter plugin.
+ *
+ * ```ts
+ * import { VueAdapter } from "@snail-js/api/plugins/vue";
+ *
+ * Service.use(VueAdapter());
+ *
+ * const user = Service.createApi(UserApi).getUser("1");
+ * // `user.meta.loading` / `meta.data` / `meta.error` are Vue refs.
+ * ```
+ *
+ * This sits behind its own subpath rather than in `@snail-js/api/plugins`: that
+ * barrel must not statically import `vue`, or an application using only `Cache`
+ * would fail to resolve Vue at all.
+ *
+ * @packageDocumentation
+ */
+export { VueAdapter } from "./plugin.js";
+export type { VueAdapterOptions } from "./type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/vue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/vue/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC"}