toolception 0.6.0 → 0.6.2

package/dist/http/http.utils.d.ts

@@ -0,0 +1,121 @@
+import { FastifyInstance, FastifyReply } from 'fastify';
+import { z } from 'zod';
+import { CustomEndpointDefinition, EndpointErrorResponse, HttpMethod, PermissionAwareEndpointHandler, RegisterCustomEndpointsOptions } from './http.types.js';
+/**
+ * Helper function to create type-safe custom endpoints with automatic type inference.
+ * Provides better IntelliSense and type checking for endpoint definitions.
+ *
+ * @template TBody - Zod schema for request body
+ * @template TQuery - Zod schema for query parameters
+ * @template TParams - Zod schema for path parameters
+ * @template TResponse - Zod schema for response
+ *
+ * @param definition - Endpoint definition with schemas and handler
+ * @returns The same endpoint definition with full type inference
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { defineEndpoint } from "toolception";
+ *
+ * const getUsersEndpoint = defineEndpoint({
+ *   method: "GET",
+ *   path: "/users",
+ *   querySchema: z.object({
+ *     limit: z.coerce.number().int().positive().default(10),
+ *     role: z.enum(["admin", "user"]).optional(),
+ *   }),
+ *   responseSchema: z.object({
+ *     users: z.array(z.object({
+ *       id: z.string(),
+ *       name: z.string(),
+ *     })),
+ *     total: z.number(),
+ *   }),
+ *   handler: async (req) => {
+ *     // req.query is fully typed: { limit: number, role?: "admin" | "user" }
+ *     const { limit, role } = req.query;
+ *
+ *     return {
+ *       users: [{ id: "1", name: "Alice" }],
+ *       total: 1,
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export declare function defineEndpoint<TBody extends z.ZodTypeAny = z.ZodNever, TQuery extends z.ZodTypeAny = z.ZodNever, TParams extends z.ZodTypeAny = z.ZodNever, TResponse extends z.ZodTypeAny = z.ZodAny>(definition: CustomEndpointDefinition<TBody, TQuery, TParams, TResponse>): CustomEndpointDefinition<TBody, TQuery, TParams, TResponse>;
+/**
+ * Helper function to create permission-aware custom endpoints for permission-based servers.
+ * Similar to defineEndpoint but with access to permission context in the handler.
+ *
+ * @template TBody - Zod schema for request body
+ * @template TQuery - Zod schema for query parameters
+ * @template TParams - Zod schema for path parameters
+ * @template TResponse - Zod schema for response
+ *
+ * @param definition - Endpoint definition with permission-aware handler
+ * @returns Endpoint definition compatible with permission-based servers
+ *
+ * @example
+ * ```typescript
+ * import { definePermissionAwareEndpoint } from "toolception";
+ *
+ * const statsEndpoint = definePermissionAwareEndpoint({
+ *   method: "GET",
+ *   path: "/my-permissions",
+ *   responseSchema: z.object({
+ *     toolsets: z.array(z.string()),
+ *     count: z.number(),
+ *   }),
+ *   handler: async (req) => {
+ *     // req.allowedToolsets and req.failedToolsets are available
+ *     return {
+ *       toolsets: req.allowedToolsets,
+ *       count: req.allowedToolsets.length,
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export declare function definePermissionAwareEndpoint<TBody extends z.ZodTypeAny = z.ZodNever, TQuery extends z.ZodTypeAny = z.ZodNever, TParams extends z.ZodTypeAny = z.ZodNever, TResponse extends z.ZodTypeAny = z.ZodAny>(definition: {
+    method: HttpMethod;
+    path: string;
+    bodySchema?: TBody;
+    querySchema?: TQuery;
+    paramsSchema?: TParams;
+    responseSchema?: TResponse;
+    handler: PermissionAwareEndpointHandler<TBody, TQuery, TParams, TResponse>;
+    description?: string;
+}): CustomEndpointDefinition<TBody, TQuery, TParams, TResponse>;
+/**
+ * Registers custom endpoints on a Fastify instance.
+ * Handles Zod validation, error responses, and type-safe request mapping.
+ *
+ * @param app - Fastify instance to register endpoints on
+ * @param basePath - Base path for all endpoints (e.g., "/" or "/api")
+ * @param endpoints - Array of custom endpoint definitions
+ * @param options - Optional configuration for endpoint registration
+ *
+ * @example
+ * ```typescript
+ * registerCustomEndpoints(app, "/api", [
+ *   defineEndpoint({
+ *     method: "GET",
+ *     path: "/users",
+ *     querySchema: z.object({ limit: z.coerce.number() }),
+ *     handler: async (req) => ({ users: [] }),
+ *   }),
+ * ]);
+ * ```
+ */
+export declare function registerCustomEndpoints(app: FastifyInstance, basePath: string, endpoints: CustomEndpointDefinition[], options?: RegisterCustomEndpointsOptions): void;
+/**
+ * Creates a standardized validation error response.
+ * @param reply - Fastify reply object
+ * @param field - The field that failed validation
+ * @param error - Zod validation error
+ * @returns Formatted error response
+ */
+export declare function createValidationError(reply: FastifyReply, field: string, error: z.ZodError): EndpointErrorResponse;
+//# sourceMappingURL=http.utils.d.ts.map

package/dist/http/http.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.utils.d.ts","sourceRoot":"","sources":["../../src/http/http.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAkB,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,wBAAwB,EAExB,qBAAqB,EACrB,UAAU,EACV,8BAA8B,EAE9B,8BAA8B,EAC/B,MAAM,iBAAiB,CAAC;AAIzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,cAAc,CAC5B,KAAK,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,EACvC,MAAM,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,EACxC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,EACzC,SAAS,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,EAEzC,UAAU,EAAE,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,GACtE,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAE7D;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,EACvC,MAAM,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,EACxC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,EACzC,SAAS,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,EACzC,UAAU,EAAE;IACZ,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,KAAK,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,cAAc,CAAC,EAAE,SAAS,CAAC;IAC3B,OAAO,EAAE,8BAA8B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAI9D;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,wBAAwB,EAAE,EACrC,OAAO,CAAC,EAAE,8BAA8B,GACvC,IAAI,CAgIN;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,CAAC,CAAC,QAAQ,GAChB,qBAAqB,CASvB"}

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { createMcpServer } from './server/createMcpServer.js';
-export type { CreateMcpServerOptions } from './server/createMcpServer.js';
+export type { CreateMcpServerOptions, CreatePermissionBasedMcpServerOptions, McpServerHandle } from './server/server.types.js';
 export { createPermissionBasedMcpServer } from './server/createPermissionBasedMcpServer.js';
-export type { ToolSetCatalog, ToolSetDefinition, McpToolDefinition, ExposurePolicy, Mode, ModuleLoader, PermissionConfig, CreatePermissionBasedMcpServerOptions, SessionContextConfig, SessionRequestContext, } from './types/index.js';
+export type { ToolSetCatalog, ToolSetDefinition, McpToolDefinition, ExposurePolicy, Mode, ModuleLoader, PermissionConfig, SessionContextConfig, SessionRequestContext, } from './types/index.js';
 export { SessionContextResolver } from './session/SessionContextResolver.js';
-export type { SessionContextResult } from './session/SessionContextResolver.js';
-export type { CustomEndpointDefinition, CustomEndpointRequest, PermissionAwareEndpointRequest, CustomEndpointHandler, PermissionAwareEndpointHandler, HttpMethod, EndpointErrorResponse, } from './http/customEndpoints.js';
-export { defineEndpoint, definePermissionAwareEndpoint, } from './http/customEndpoints.js';
+export type { SessionContextResult } from './session/session.types.js';
+export type { CustomEndpointDefinition, CustomEndpointRequest, PermissionAwareEndpointRequest, CustomEndpointHandler, PermissionAwareEndpointHandler, HttpMethod, EndpointErrorResponse, } from './http/http.types.js';
+export { defineEndpoint, definePermissionAwareEndpoint, } from './http/http.utils.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAG1E,OAAO,EAAE,8BAA8B,EAAE,MAAM,4CAA4C,CAAC;AAG5F,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,gBAAgB,EAChB,qCAAqC,EACrC,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,YAAY,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAGhF,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,8BAA8B,EAC9B,qBAAqB,EACrB,8BAA8B,EAC9B,UAAU,EACV,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,cAAc,EACd,6BAA6B,GAC9B,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,YAAY,EAAE,sBAAsB,EAAE,qCAAqC,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAG/H,OAAO,EAAE,8BAA8B,EAAE,MAAM,4CAA4C,CAAC;AAG5F,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAGvE,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,8BAA8B,EAC9B,qBAAqB,EACrB,8BAA8B,EAC9B,UAAU,EACV,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,cAAc,EACd,6BAA6B,GAC9B,MAAM,sBAAsB,CAAC"}