@hypequery/serve 0.0.4 → 0.0.5

package/dist/endpoint.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+const fallbackSchema = z.any();
+const resolveQueryRunner = (query) => {
+    if (!query) {
+        return null;
+    }
+    const fn = typeof query === "function"
+        ? query
+        : typeof query === "object" && typeof query.run === "function"
+            ? query.run.bind(query)
+            : null;
+    if (!fn) {
+        return null;
+    }
+    return async (args) => {
+        return fn(args);
+    };
+};
+export const createEndpoint = (key, definition) => {
+    const method = definition.method ?? "GET";
+    const metadata = {
+        path: "",
+        method: method,
+        name: definition.name ?? definition.summary ?? key,
+        summary: definition.summary,
+        description: definition.description,
+        tags: definition.tags ?? [],
+        requiresAuth: definition.auth ? true : undefined,
+        deprecated: undefined,
+        visibility: "public",
+        custom: definition.custom,
+    };
+    const runner = resolveQueryRunner(definition.query);
+    const handler = async (ctx) => {
+        if (!runner) {
+            throw new Error(`Endpoint "${key}" is missing an executable query`);
+        }
+        return runner({
+            input: ctx.input,
+            ctx: ctx,
+        });
+    };
+    const outputSchema = (definition.outputSchema ?? fallbackSchema);
+    const inputSchema = definition.inputSchema;
+    return {
+        key,
+        method,
+        inputSchema,
+        outputSchema,
+        handler,
+        query: definition.query,
+        middlewares: definition.middlewares ?? [],
+        auth: definition.auth ?? null,
+        tenant: definition.tenant,
+        metadata,
+        cacheTtlMs: definition.cacheTtlMs ?? null,
+        defaultHeaders: undefined,
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./types.js";
+export * from "./server.js";
+export * from "./router.js";
+export * from "./endpoint.js";
+export * from "./openapi.js";
+export * from "./docs-ui.js";
+export * from "./auth.js";
+export * from "./client-config.js";
+export * from "./adapters/node.js";
+export * from "./adapters/fetch.js";
+export * from "./adapters/vercel.js";
+export * from "./dev.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,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./types.js";
+export * from "./server.js";
+export * from "./router.js";
+export * from "./endpoint.js";
+export * from "./openapi.js";
+export * from "./docs-ui.js";
+export * from "./auth.js";
+export * from "./client-config.js";
+export * from "./adapters/node.js";
+export * from "./adapters/fetch.js";
+export * from "./adapters/vercel.js";
+export * from "./dev.js";

package/dist/openapi.d.ts

@@ -0,0 +1,3 @@
+import type { OpenApiDocument, OpenApiOptions, ServeEndpoint } from "./types.js";
+export declare const buildOpenApiDocument: (endpoints: ServeEndpoint<any, any, any, any>[], options?: OpenApiOptions) => OpenApiDocument;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqLjF,eAAO,MAAM,oBAAoB,GAC/B,WAAW,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAC9C,UAAU,cAAc,KACvB,eAyCF,CAAC"}

package/dist/openapi.js

@@ -0,0 +1,189 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+const ERROR_SCHEMA = {
+    type: "object",
+    properties: {
+        error: {
+            type: "object",
+            properties: {
+                type: { type: "string" },
+                message: { type: "string" },
+                details: { type: "object" },
+            },
+            required: ["type", "message"],
+        },
+    },
+    required: ["error"],
+};
+const dereferenceSchema = (schema) => {
+    if (!schema || typeof schema !== "object") {
+        return schema;
+    }
+    if (schema.$ref && schema.definitions) {
+        const refKey = String(schema.$ref).split("/").pop();
+        if (refKey && schema.definitions[refKey]) {
+            return schema.definitions[refKey];
+        }
+    }
+    return schema;
+};
+const removeDefinitions = (schema) => {
+    if (!schema || typeof schema !== "object") {
+        return schema;
+    }
+    // Handle arrays
+    if (Array.isArray(schema)) {
+        return schema.map(item => removeDefinitions(item));
+    }
+    // If this schema has a $ref and definitions, inline the definition
+    if (schema.$ref && schema.definitions) {
+        const refKey = String(schema.$ref).split("/").pop();
+        if (refKey && schema.definitions[refKey]) {
+            const resolved = schema.definitions[refKey];
+            delete schema.$ref;
+            delete schema.definitions;
+            return removeDefinitions({ ...schema, ...resolved });
+        }
+    }
+    // Remove definitions property if it exists
+    const { definitions: _definitions, $ref: _ref, ...rest } = schema;
+    // Recursively clean nested objects and arrays
+    const result = {};
+    for (const [key, value] of Object.entries(rest)) {
+        if (Array.isArray(value)) {
+            result[key] = value.map(item => typeof item === "object" && item !== null ? removeDefinitions(item) : item);
+        }
+        else if (typeof value === "object" && value !== null) {
+            result[key] = removeDefinitions(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+};
+const toJsonSchema = (schema, name) => {
+    if (!schema) {
+        return { type: "object" };
+    }
+    const jsonSchema = zodToJsonSchema(schema, {
+        target: "openApi3",
+        name,
+        $refStrategy: "none",
+    });
+    return removeDefinitions(jsonSchema);
+};
+const toQueryParameters = (schema, name) => {
+    if (!schema) {
+        return [];
+    }
+    const jsonSchema = dereferenceSchema(toJsonSchema(schema, name));
+    if (!jsonSchema || typeof jsonSchema !== "object") {
+        return [];
+    }
+    const schemaType = jsonSchema.type;
+    const isObjectType = schemaType === "object" || (Array.isArray(schemaType) && schemaType.includes("object"));
+    if (!isObjectType || typeof jsonSchema.properties !== "object") {
+        return [];
+    }
+    const properties = jsonSchema.properties;
+    const requiredSet = new Set(Array.isArray(jsonSchema.required) ? jsonSchema.required : []);
+    return Object.entries(properties).map(([key, value]) => ({
+        name: key,
+        in: "query",
+        required: requiredSet.has(key),
+        schema: value,
+    }));
+};
+const toOperation = (endpoint, nameSuffix) => {
+    const operation = {
+        operationId: endpoint.key,
+        summary: endpoint.metadata.summary,
+        description: endpoint.metadata.description,
+        tags: endpoint.metadata.tags.length ? endpoint.metadata.tags : undefined,
+        responses: {
+            200: {
+                description: "Successful response",
+                content: {
+                    "application/json": {
+                        schema: toJsonSchema(endpoint.outputSchema, `${endpoint.key}${nameSuffix}`),
+                    },
+                },
+            },
+            default: {
+                description: "Error response",
+                content: {
+                    "application/json": {
+                        schema: ERROR_SCHEMA,
+                    },
+                },
+            },
+        },
+    };
+    const queryParameters = endpoint.method === "GET"
+        ? toQueryParameters(endpoint.inputSchema, `${endpoint.key}Query`)
+        : [];
+    if (queryParameters.length > 0) {
+        operation.parameters = queryParameters;
+    }
+    else if (endpoint.inputSchema) {
+        operation.requestBody = {
+            required: true,
+            content: {
+                "application/json": {
+                    schema: toJsonSchema(endpoint.inputSchema, `${endpoint.key}Request`),
+                },
+            },
+        };
+    }
+    if (endpoint.metadata.requiresAuth) {
+        operation.security = [{ ApiKeyAuth: [] }];
+    }
+    return operation;
+};
+const normalizeInfo = (options) => {
+    const info = options?.info;
+    return {
+        title: info?.title ?? "hypequery API",
+        version: options?.version ?? "1.0.0",
+        description: info?.description,
+        termsOfService: info?.termsOfService,
+        contact: info?.contact,
+        license: info?.license,
+    };
+};
+export const buildOpenApiDocument = (endpoints, options) => {
+    var _a;
+    const document = {
+        openapi: "3.1.0",
+        info: normalizeInfo(options),
+        servers: options?.servers ?? [],
+        paths: {},
+    };
+    let needsSecurityScheme = false;
+    for (const endpoint of endpoints) {
+        if (endpoint.metadata.visibility && endpoint.metadata.visibility !== "public") {
+            continue;
+        }
+        const path = endpoint.metadata.path || "/";
+        const method = endpoint.method.toLowerCase();
+        const pathItem = ((_a = document.paths)[path] ?? (_a[path] = {}));
+        const operation = toOperation(endpoint, "Response");
+        if (endpoint.metadata.requiresAuth) {
+            needsSecurityScheme = true;
+        }
+        pathItem[method] = operation;
+    }
+    if (needsSecurityScheme) {
+        document.components = {
+            ...(document.components ?? {}),
+            securitySchemes: {
+                ApiKeyAuth: {
+                    type: "apiKey",
+                    name: "Authorization",
+                    in: "header",
+                },
+            },
+        };
+    }
+    return document;
+};

package/dist/pipeline.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import type { AuthContext, AuthStrategy, DocsOptions, OpenApiOptions, ServeContextFactory, ServeEndpoint, ServeHandler, ServeLifecycleHooks, ServeMiddleware, ServeRequest, ServeResponse, TenantConfig } from './types.js';
+export interface ExecuteEndpointOptions<TContext extends Record<string, unknown>, TAuth extends AuthContext> {
+    endpoint: ServeEndpoint<any, any, TContext, TAuth>;
+    request: ServeRequest;
+    requestId?: string;
+    authStrategies: AuthStrategy<TAuth>[];
+    contextFactory?: ServeContextFactory<TContext, TAuth>;
+    globalMiddlewares: ServeMiddleware<any, any, TContext, TAuth>[];
+    tenantConfig?: TenantConfig<TAuth>;
+    hooks?: ServeLifecycleHooks<TAuth>;
+    additionalContext?: Partial<TContext>;
+}
+export declare const executeEndpoint: <TContext extends Record<string, unknown>, TAuth extends AuthContext>(options: ExecuteEndpointOptions<TContext, TAuth>) => Promise<ServeResponse>;
+interface HandlerOptions<TContext extends Record<string, unknown>, TAuth extends AuthContext> {
+    router: import('./router.js').ServeRouter;
+    globalMiddlewares: ServeMiddleware<any, any, TContext, TAuth>[];
+    authStrategies: AuthStrategy<TAuth>[];
+    tenantConfig?: TenantConfig<TAuth>;
+    contextFactory?: ServeContextFactory<TContext, TAuth>;
+    hooks?: ServeLifecycleHooks<TAuth>;
+}
+export declare const createServeHandler: <TContext extends Record<string, unknown>, TAuth extends AuthContext>({ router, globalMiddlewares, authStrategies, tenantConfig, contextFactory, hooks, }: HandlerOptions<TContext, TAuth>) => ServeHandler;
+export declare const createOpenApiEndpoint: (path: string, getEndpoints: () => ServeEndpoint<any, any, any, any>[], options?: OpenApiOptions) => {
+    key: string;
+    method: "GET";
+    inputSchema: undefined;
+    outputSchema: z.ZodAny;
+    handler: () => Promise<unknown>;
+    query: undefined;
+    middlewares: never[];
+    auth: null;
+    metadata: {
+        path: string;
+        method: "GET";
+        name: string;
+        summary: string;
+        description: string;
+        tags: string[];
+        requiresAuth: false;
+        deprecated: false;
+        visibility: "internal";
+    };
+    cacheTtlMs: null;
+};
+export declare const createDocsEndpoint: (path: string, openapiPath: string, options?: DocsOptions) => {
+    key: string;
+    method: "GET";
+    inputSchema: undefined;
+    outputSchema: z.ZodString;
+    handler: () => Promise<string>;
+    query: undefined;
+    middlewares: never[];
+    auth: null;
+    metadata: {
+        path: string;
+        method: "GET";
+        name: string;
+        summary: string;
+        description: string;
+        tags: string[];
+        requiresAuth: false;
+        deprecated: false;
+        visibility: "internal";
+    };
+    cacheTtlMs: null;
+    defaultHeaders: {
+        'content-type': string;
+    };
+};
+export {};
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAC;AAEzC,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EAKX,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EAEb,MAAM,YAAY,CAAC;AAiIpB,MAAM,WAAW,sBAAsB,CACrC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW;IAEzB,QAAQ,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACnD,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;IACtC,cAAc,CAAC,EAAE,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACtD,iBAAiB,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;IAChE,YAAY,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACnC,iBAAiB,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;CACvC;AAED,eAAO,MAAM,eAAe,GAC1B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EAEzB,SAAS,sBAAsB,CAAC,QAAQ,EAAE,KAAK,CAAC,KAC/C,OAAO,CAAC,aAAa,CA0LvB,CAAC;AAEF,UAAU,cAAc,CACtB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW;IAEzB,MAAM,EAAE,OAAO,aAAa,EAAE,WAAW,CAAC;IAC1C,iBAAiB,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;IAChE,cAAc,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;IACtC,YAAY,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,cAAc,CAAC,EAAE,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;CACpC;AAED,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EACzB,qFAOC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAG,YAqBpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,cAAc,MAAM,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EACvD,UAAU,cAAc;;;;;;;;;;;;;;;;;;;;;CA8BzB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,MAAM,MAAM,EACZ,aAAa,MAAM,EACnB,UAAU,WAAW;;;;;;;;;;;;;;;;;;;;;;;;CAyBmD,CAAC"}

package/dist/pipeline.js

@@ -0,0 +1,317 @@
+import { z } from 'zod';
+import { createTenantScope, warnTenantMisconfiguration } from './tenant.js';
+import { generateRequestId } from './utils.js';
+import { buildOpenApiDocument } from './openapi.js';
+import { buildDocsHtml } from './docs-ui.js';
+const safeInvokeHook = async (name, hook, payload) => {
+    if (!hook)
+        return;
+    try {
+        await hook(payload);
+    }
+    catch (error) {
+        console.error(`[hypequery/serve] ${name} hook failed`, error);
+    }
+};
+const createErrorResponse = (status, type, message, details) => ({
+    status,
+    body: { error: { type, message, ...(details ? { details } : {}) } },
+});
+const buildContextInput = (request) => {
+    if (request.body !== undefined && request.body !== null) {
+        return request.body;
+    }
+    if (request.query && Object.keys(request.query).length > 0) {
+        return request.query;
+    }
+    return {};
+};
+const runMiddlewares = async (middlewares, ctx, handler) => {
+    let current = handler;
+    for (let i = middlewares.length - 1; i >= 0; i -= 1) {
+        const middleware = middlewares[i];
+        const next = current;
+        current = () => middleware(ctx, next);
+    }
+    return current();
+};
+const authenticateRequest = async (strategies, request, metadata) => {
+    for (const strategy of strategies) {
+        const result = await strategy({ request, endpoint: metadata });
+        if (result) {
+            return result;
+        }
+    }
+    return null;
+};
+const gatherAuthStrategies = (endpointStrategy, globalStrategies) => {
+    const combined = [];
+    if (endpointStrategy)
+        combined.push(endpointStrategy);
+    combined.push(...globalStrategies);
+    return combined;
+};
+const computeRequiresAuth = (metadata, endpointStrategy, globalStrategies) => {
+    if (typeof metadata.requiresAuth === 'boolean') {
+        return metadata.requiresAuth;
+    }
+    if (endpointStrategy) {
+        return true;
+    }
+    return globalStrategies.length > 0;
+};
+const validateInput = (schema, payload) => {
+    if (!schema) {
+        return { success: true, data: payload };
+    }
+    const result = schema.safeParse(payload);
+    return result.success
+        ? { success: true, data: result.data }
+        : { success: false, error: result.error };
+};
+const cloneContext = (ctx) => (ctx ? { ...ctx } : {});
+const resolveContext = async (factory, request, auth) => {
+    if (!factory) {
+        return {};
+    }
+    if (typeof factory === 'function') {
+        const value = await factory({ request, auth });
+        return cloneContext(value);
+    }
+    return cloneContext(factory);
+};
+const resolveRequestId = (request, provided) => provided ?? request.headers['x-request-id'] ?? request.headers['x-trace-id'] ?? generateRequestId();
+export const executeEndpoint = async (options) => {
+    const { endpoint, request, requestId: explicitRequestId, authStrategies, contextFactory, globalMiddlewares, tenantConfig, hooks = {}, additionalContext, } = options;
+    const requestId = resolveRequestId(request, explicitRequestId);
+    const locals = {};
+    let cacheTtlMs = endpoint.cacheTtlMs ?? null;
+    const setCacheTtl = (ttl) => {
+        cacheTtlMs = ttl;
+    };
+    const context = {
+        request,
+        input: buildContextInput(request),
+        auth: null,
+        metadata: endpoint.metadata,
+        locals,
+        setCacheTtl,
+    };
+    const startedAt = Date.now();
+    await safeInvokeHook('onRequestStart', hooks.onRequestStart, {
+        requestId,
+        queryKey: endpoint.key,
+        metadata: endpoint.metadata,
+        request,
+        auth: context.auth,
+    });
+    try {
+        const endpointAuth = endpoint.auth ?? null;
+        const strategies = gatherAuthStrategies(endpointAuth, authStrategies ?? []);
+        const requiresAuth = computeRequiresAuth(endpoint.metadata, endpointAuth, authStrategies ?? []);
+        const metadataWithAuth = {
+            ...endpoint.metadata,
+            requiresAuth,
+        };
+        context.metadata = metadataWithAuth;
+        const authContext = await authenticateRequest(strategies, request, metadataWithAuth);
+        if (!authContext && requiresAuth) {
+            await safeInvokeHook('onAuthFailure', hooks.onAuthFailure, {
+                requestId,
+                queryKey: endpoint.key,
+                metadata: metadataWithAuth,
+                request,
+                auth: context.auth,
+                reason: 'MISSING',
+            });
+            return createErrorResponse(401, 'UNAUTHORIZED', 'Authentication required', {
+                reason: 'missing_credentials',
+                strategies_attempted: strategies.length,
+                endpoint: endpoint.metadata.path,
+            });
+        }
+        context.auth = authContext;
+        const resolvedContext = await resolveContext(contextFactory, request, authContext);
+        Object.assign(context, resolvedContext, additionalContext);
+        const activeTenantConfig = endpoint.tenant ?? tenantConfig;
+        if (activeTenantConfig) {
+            const tenantRequired = activeTenantConfig.required !== false;
+            const tenantId = authContext ? activeTenantConfig.extract(authContext) : null;
+            if (!tenantId && tenantRequired) {
+                const errorMessage = activeTenantConfig.errorMessage ??
+                    'Tenant context is required but could not be determined from authentication';
+                await safeInvokeHook('onError', hooks.onError, {
+                    requestId,
+                    queryKey: endpoint.key,
+                    metadata: metadataWithAuth,
+                    request,
+                    auth: context.auth,
+                    durationMs: Date.now() - startedAt,
+                    error: new Error(errorMessage),
+                });
+                return createErrorResponse(403, 'UNAUTHORIZED', errorMessage, {
+                    reason: 'missing_tenant_context',
+                    tenant_required: true,
+                });
+            }
+            if (tenantId) {
+                context.tenantId = tenantId;
+                const mode = activeTenantConfig.mode ?? 'manual';
+                const column = activeTenantConfig.column;
+                if (mode === 'auto-inject' && column) {
+                    const contextValues = context;
+                    for (const key of Object.keys(contextValues)) {
+                        const value = contextValues[key];
+                        if (value && typeof value === 'object' && 'table' in value && typeof value.table === 'function') {
+                            contextValues[key] = createTenantScope(value, {
+                                tenantId,
+                                column,
+                            });
+                        }
+                    }
+                }
+                else if (mode === 'manual') {
+                    warnTenantMisconfiguration({
+                        queryKey: endpoint.key,
+                        hasTenantConfig: true,
+                        hasTenantId: true,
+                        mode: 'manual',
+                    });
+                }
+            }
+            else if (!tenantRequired) {
+                warnTenantMisconfiguration({
+                    queryKey: endpoint.key,
+                    hasTenantConfig: true,
+                    hasTenantId: false,
+                    mode: activeTenantConfig.mode,
+                });
+            }
+        }
+        const validationResult = validateInput(endpoint.inputSchema, context.input);
+        if (!validationResult.success) {
+            await safeInvokeHook('onError', hooks.onError, {
+                requestId,
+                queryKey: endpoint.key,
+                metadata: metadataWithAuth,
+                request,
+                auth: context.auth,
+                durationMs: Date.now() - startedAt,
+                error: validationResult.error,
+            });
+            return createErrorResponse(400, 'VALIDATION_ERROR', 'Request validation failed', {
+                issues: validationResult.error.issues,
+            });
+        }
+        context.input = validationResult.data;
+        const pipeline = [
+            ...(globalMiddlewares ?? []),
+            ...endpoint.middlewares,
+        ];
+        const result = await runMiddlewares(pipeline, context, () => endpoint.handler(context));
+        const headers = { ...(endpoint.defaultHeaders ?? {}) };
+        if (typeof cacheTtlMs === 'number') {
+            headers['cache-control'] = cacheTtlMs > 0 ? `public, max-age=${Math.floor(cacheTtlMs / 1000)}` : 'no-store';
+        }
+        const durationMs = Date.now() - startedAt;
+        await safeInvokeHook('onRequestEnd', hooks.onRequestEnd, {
+            requestId,
+            queryKey: endpoint.key,
+            metadata: metadataWithAuth,
+            request,
+            auth: context.auth,
+            durationMs,
+            result,
+        });
+        return {
+            status: 200,
+            headers,
+            body: result,
+        };
+    }
+    catch (error) {
+        await safeInvokeHook('onError', hooks.onError, {
+            requestId,
+            queryKey: endpoint.key,
+            metadata: context.metadata,
+            request,
+            auth: context.auth,
+            durationMs: Date.now() - startedAt,
+            error,
+        });
+        const message = error instanceof Error ? error.message : 'Unexpected error';
+        return createErrorResponse(500, 'INTERNAL_SERVER_ERROR', message);
+    }
+};
+export const createServeHandler = ({ router, globalMiddlewares, authStrategies, tenantConfig, contextFactory, hooks, }) => {
+    return async (request) => {
+        const endpoint = router.match(request.method, request.path);
+        if (!endpoint) {
+            return createErrorResponse(404, 'NOT_FOUND', `No endpoint registered for ${request.method} ${request.path}`);
+        }
+        return executeEndpoint({
+            endpoint,
+            request,
+            authStrategies,
+            contextFactory,
+            globalMiddlewares,
+            tenantConfig,
+            hooks,
+        });
+    };
+};
+export const createOpenApiEndpoint = (path, getEndpoints, options) => {
+    let cachedDocument = null;
+    return {
+        key: '__hypequery_openapi__',
+        method: 'GET',
+        inputSchema: undefined,
+        outputSchema: z.any(),
+        handler: async () => {
+            if (!cachedDocument) {
+                cachedDocument = buildOpenApiDocument(getEndpoints(), options);
+            }
+            return cachedDocument;
+        },
+        query: undefined,
+        middlewares: [],
+        auth: null,
+        metadata: {
+            path,
+            method: 'GET',
+            name: 'OpenAPI schema',
+            summary: 'OpenAPI schema',
+            description: 'Generated OpenAPI specification for the registered endpoints',
+            tags: ['docs'],
+            requiresAuth: false,
+            deprecated: false,
+            visibility: 'internal',
+        },
+        cacheTtlMs: null,
+    };
+};
+export const createDocsEndpoint = (path, openapiPath, options) => ({
+    key: '__hypequery_docs__',
+    method: 'GET',
+    inputSchema: undefined,
+    outputSchema: z.string(),
+    handler: async () => buildDocsHtml(openapiPath, options),
+    query: undefined,
+    middlewares: [],
+    auth: null,
+    metadata: {
+        path,
+        method: 'GET',
+        name: 'Docs',
+        summary: 'API documentation',
+        description: 'Auto-generated documentation for your hypequery endpoints',
+        tags: ['docs'],
+        requiresAuth: false,
+        deprecated: false,
+        visibility: 'internal',
+    },
+    cacheTtlMs: null,
+    defaultHeaders: {
+        'content-type': 'text/html; charset=utf-8',
+    },
+});