toolception 0.3.0 → 0.5.0

package/dist/http/customEndpoints.d.ts

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+/**
+ * Supported HTTP methods for custom endpoints
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/**
+ * Request context passed to custom endpoint handlers.
+ * Contains validated and typed request data without exposing Fastify types.
+ */
+export interface CustomEndpointRequest<TBody = unknown, TQuery = unknown, TParams = unknown> {
+    /**
+     * Validated request body (typed from bodySchema)
+     */
+    body: TBody;
+    /**
+     * Validated query parameters (typed from querySchema)
+     */
+    query: TQuery;
+    /**
+     * Validated path parameters (typed from paramsSchema)
+     */
+    params: TParams;
+    /**
+     * Raw request headers
+     */
+    headers: Record<string, string | string[] | undefined>;
+    /**
+     * Client ID (from mcp-client-id header or auto-generated for anonymous clients)
+     */
+    clientId: string;
+}
+/**
+ * Permission-aware request context for custom endpoints in permission-based servers.
+ * Extends CustomEndpointRequest with permission information.
+ */
+export interface PermissionAwareEndpointRequest<TBody = unknown, TQuery = unknown, TParams = unknown> extends CustomEndpointRequest<TBody, TQuery, TParams> {
+    /**
+     * Toolsets this client is allowed to access (resolved from permissions)
+     */
+    allowedToolsets: string[];
+    /**
+     * Toolsets that failed to enable for this client
+     */
+    failedToolsets: string[];
+}
+/**
+ * Handler function type with automatic type inference from Zod schemas.
+ * Receives validated and typed request data, returns typed response.
+ */
+export type CustomEndpointHandler<TBody extends z.ZodTypeAny, TQuery extends z.ZodTypeAny, TParams extends z.ZodTypeAny, TResponse extends z.ZodTypeAny> = (request: CustomEndpointRequest<TBody extends z.ZodTypeAny ? z.infer<TBody> : never, TQuery extends z.ZodTypeAny ? z.infer<TQuery> : never, TParams extends z.ZodTypeAny ? z.infer<TParams> : never>) => Promise<z.infer<TResponse>> | z.infer<TResponse>;
+/**
+ * Permission-aware handler function type for permission-based servers.
+ * Receives permission context in addition to validated request data.
+ */
+export type PermissionAwareEndpointHandler<TBody extends z.ZodTypeAny, TQuery extends z.ZodTypeAny, TParams extends z.ZodTypeAny, TResponse extends z.ZodTypeAny> = (request: PermissionAwareEndpointRequest<TBody extends z.ZodTypeAny ? z.infer<TBody> : never, TQuery extends z.ZodTypeAny ? z.infer<TQuery> : never, TParams extends z.ZodTypeAny ? z.infer<TParams> : never>) => Promise<z.infer<TResponse>> | z.infer<TResponse>;
+/**
+ * Custom HTTP endpoint definition with Zod schema-based validation and type inference.
+ * Allows defining REST-like endpoints alongside MCP protocol endpoints.
+ *
+ * @template TBody - Zod schema for request body validation
+ * @template TQuery - Zod schema for query parameter validation
+ * @template TParams - Zod schema for path parameter validation
+ * @template TResponse - Zod schema for response validation
+ *
+ * @example
+ * ```typescript
+ * const getUserEndpoint = defineEndpoint({
+ *   method: "GET",
+ *   path: "/users/:userId",
+ *   paramsSchema: z.object({
+ *     userId: z.string().uuid(),
+ *   }),
+ *   responseSchema: z.object({
+ *     id: z.string(),
+ *     name: z.string(),
+ *   }),
+ *   handler: async (req) => {
+ *     // req.params is typed: { userId: string }
+ *     const { userId } = req.params;
+ *     return { id: userId, name: "Alice" };
+ *   },
+ * });
+ * ```
+ */
+export interface CustomEndpointDefinition<TBody extends z.ZodTypeAny = z.ZodTypeAny, TQuery extends z.ZodTypeAny = z.ZodTypeAny, TParams extends z.ZodTypeAny = z.ZodTypeAny, TResponse extends z.ZodTypeAny = z.ZodTypeAny> {
+    /**
+     * HTTP method for this endpoint
+     */
+    method: HttpMethod;
+    /**
+     * URL path (relative to basePath). Supports path parameters using :param syntax.
+     *
+     * @example
+     * - "/users" - Simple path
+     * - "/users/:id" - Path with single parameter
+     * - "/items/:category/:id" - Path with multiple parameters
+     */
+    path: string;
+    /**
+     * Optional Zod schema for request body validation (typically used with POST, PUT, PATCH).
+     * Enables automatic type inference for handler body parameter.
+     */
+    bodySchema?: TBody;
+    /**
+     * Optional Zod schema for query parameter validation.
+     * Enables automatic type inference for handler query parameter.
+     *
+     * @example
+     * ```typescript
+     * querySchema: z.object({
+     *   limit: z.coerce.number().int().positive().default(10),
+     *   offset: z.coerce.number().int().nonnegative().default(0),
+     * })
+     * ```
+     */
+    querySchema?: TQuery;
+    /**
+     * Optional Zod schema for path parameter validation.
+     * Enables automatic type inference for handler params parameter.
+     */
+    paramsSchema?: TParams;
+    /**
+     * Optional Zod schema for response validation.
+     * Enables automatic type inference for handler return type.
+     * If validation fails, returns 500 error to prevent information leakage.
+     */
+    responseSchema?: TResponse;
+    /**
+     * Request handler function with inferred types from schemas.
+     * Receives validated and typed request data, returns typed response.
+     */
+    handler: CustomEndpointHandler<TBody, TQuery, TParams, TResponse>;
+    /**
+     * Optional description for documentation purposes
+     */
+    description?: string;
+}
+/**
+ * Standard error response structure for custom endpoints
+ */
+export interface EndpointErrorResponse {
+    error: {
+        /**
+         * Error code indicating the type of error
+         * - VALIDATION_ERROR: Request validation failed (400)
+         * - INTERNAL_ERROR: Handler threw an error (500)
+         * - RESPONSE_VALIDATION_ERROR: Response validation failed (500)
+         */
+        code: "VALIDATION_ERROR" | "INTERNAL_ERROR" | "RESPONSE_VALIDATION_ERROR";
+        /**
+         * Human-readable error message
+         */
+        message: string;
+        /**
+         * Optional additional error details (e.g., Zod validation errors)
+         */
+        details?: unknown;
+    };
+}
+/**
+ * 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>;
+//# sourceMappingURL=customEndpoints.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"customEndpoints.d.ts","sourceRoot":"","sources":["../../src/http/customEndpoints.ts"],"names":[],"mappings":"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"}

package/dist/http/endpointRegistration.d.ts

@@ -0,0 +1,35 @@
+import { FastifyInstance, FastifyRequest } from 'fastify';
+import { CustomEndpointDefinition } from './customEndpoints.js';
+/**
+ * Options for registering custom endpoints
+ */
+export interface RegisterCustomEndpointsOptions {
+    /**
+     * Optional function to extract additional context for each request.
+     * Used by permission-aware transport to inject permission data.
+     */
+    contextExtractor?: (req: FastifyRequest) => Promise<Record<string, any>> | Record<string, any>;
+}
+/**
+ * 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;
+//# sourceMappingURL=endpointRegistration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"endpointRegistration.d.ts","sourceRoot":"","sources":["../../src/http/endpointRegistration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAgB,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EACV,wBAAwB,EAGzB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CACjB,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;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"}

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export { createMcpServer } from './server/createMcpServer.js';
 export type { CreateMcpServerOptions } from './server/createMcpServer.js';
 export { createPermissionBasedMcpServer } from './server/createPermissionBasedMcpServer.js';
 export type { ToolSetCatalog, ToolSetDefinition, McpToolDefinition, ExposurePolicy, Mode, ModuleLoader, PermissionConfig, CreatePermissionBasedMcpServerOptions, } from './types/index.js';
+export type { CustomEndpointDefinition, CustomEndpointRequest, PermissionAwareEndpointRequest, CustomEndpointHandler, PermissionAwareEndpointHandler, HttpMethod, EndpointErrorResponse, } from './http/customEndpoints.js';
+export { defineEndpoint, definePermissionAwareEndpoint, } from './http/customEndpoints.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,GACtC,MAAM,kBAAkB,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,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,GACtC,MAAM,kBAAkB,CAAC;AAG1B,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"}