@hypequery/serve 0.0.1

package/dist/server.js

@@ -0,0 +1,580 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { startNodeServer } from "./adapters/node.js";
+import { createEndpoint } from "./endpoint.js";
+import { buildOpenApiDocument } from "./openapi.js";
+import { applyBasePath, normalizeRoutePath, ServeRouter } from "./router.js";
+import { buildDocsHtml } from "./docs-ui.js";
+import { createTenantScope, warnTenantMisconfiguration } from "./tenant.js";
+const ensureArray = (value) => {
+    if (!value) {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+};
+const generateRequestId = () => {
+    return `req_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+};
+const createProcedureBuilder = () => {
+    const build = (state) => {
+        return {
+            input: (schema) => build({ ...state, inputSchema: schema }),
+            output: (schema) => build({ ...state, outputSchema: schema }),
+            describe: (description) => build({ ...state, description }),
+            summary: (summary) => build({ ...state, summary }),
+            tag: (tag) => build({
+                ...state,
+                tags: Array.from(new Set([...state.tags, tag])),
+            }),
+            tags: (tags) => build({
+                ...state,
+                tags: Array.from(new Set([...state.tags, ...(tags ?? [])])),
+            }),
+            method: (method) => build({ ...state, method }),
+            cache: (ttlMs) => build({ ...state, cacheTtlMs: ttlMs }),
+            auth: (strategy) => build({ ...state, auth: strategy }),
+            tenant: (config) => build({ ...state, tenant: config }),
+            custom: (custom) => build({
+                ...state,
+                custom: { ...(state.custom ?? {}), ...custom },
+            }),
+            use: (...middlewares) => build({
+                ...state,
+                middlewares: [...state.middlewares, ...middlewares],
+            }),
+            query: (executable) => {
+                const base = {
+                    description: state.description,
+                    summary: state.summary,
+                    tags: state.tags,
+                    method: state.method,
+                    inputSchema: state.inputSchema,
+                    outputSchema: state.outputSchema,
+                    cacheTtlMs: state.cacheTtlMs,
+                    auth: typeof state.auth === "undefined" ? null : state.auth,
+                    tenant: state.tenant,
+                    custom: state.custom,
+                    middlewares: state.middlewares,
+                    query: executable,
+                };
+                return base;
+            },
+        };
+    };
+    return build({ tags: [], middlewares: [] });
+};
+const getRequestId = (request) => {
+    return (request.headers["x-request-id"] ??
+        request.headers["x-trace-id"] ??
+        generateRequestId());
+};
+const safeInvokeHook = async (name, hook, payload) => {
+    if (!hook) {
+        return;
+    }
+    try {
+        await hook(payload);
+    }
+    catch (error) {
+        console.error(`[hypequery/serve] ${name} hook failed`, error);
+    }
+};
+const mergeTags = (existing, next) => {
+    const merged = [...existing, ...(next ?? [])];
+    return Array.from(new Set(merged.filter(Boolean)));
+};
+const createErrorResponse = (status, type, message, details) => {
+    return {
+        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 index = middlewares.length - 1;
+    let next = handler;
+    while (index >= 0) {
+        const middleware = middlewares[index];
+        const downstream = next;
+        next = () => middleware(ctx, downstream);
+        index -= 1;
+    }
+    return next();
+};
+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 strategies = [];
+    if (endpointStrategy) {
+        strategies.push(endpointStrategy);
+    }
+    return [...strategies, ...globalStrategies];
+};
+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 createOpenApiEndpoint = (path, getEndpoints, openapiOptions) => {
+    // Cache the OpenAPI document to avoid rebuilding on every request
+    let cachedDocument = null;
+    return {
+        key: "__hypequery_openapi__",
+        method: "GET",
+        inputSchema: undefined,
+        outputSchema: z.any(),
+        handler: async () => {
+            if (!cachedDocument) {
+                cachedDocument = buildOpenApiDocument(getEndpoints(), openapiOptions);
+            }
+            return cachedDocument;
+        },
+        query: undefined,
+        middlewares: [],
+        auth: null,
+        metadata: {
+            path,
+            method: "GET",
+            summary: "OpenAPI schema",
+            description: "Generated OpenAPI specification for the registered endpoints",
+            tags: ["docs"],
+            requiresAuth: false,
+            deprecated: false,
+            visibility: "internal",
+        },
+        cacheTtlMs: null,
+    };
+};
+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",
+        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",
+    },
+});
+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 executeEndpoint = async (options) => {
+    const { endpoint, request, requestId, authStrategies, contextFactory, globalMiddlewares, globalTenantConfig, hooks, additionalContext, } = options;
+    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,
+            });
+        }
+        // After the auth check above, if requiresAuth is true, authContext is guaranteed to be non-null
+        context.auth = authContext;
+        const hydratedContext = await resolveContext(contextFactory, request, authContext);
+        Object.assign(context, hydratedContext, additionalContext);
+        // Tenant isolation: Extract and validate tenant ID if configured
+        // Use endpoint-specific config, or fall back to global config
+        const tenantConfig = endpoint.tenant ?? globalTenantConfig;
+        if (tenantConfig) {
+            const tenantRequired = tenantConfig.required !== false; // Default to true
+            const tenantId = authContext ? tenantConfig.extract(authContext) : null;
+            if (!tenantId && tenantRequired) {
+                const errorMessage = tenantConfig.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;
+                // Auto-inject tenant filtering if configured
+                const mode = tenantConfig.mode ?? 'manual'; // Default to manual for backward compatibility
+                const column = tenantConfig.column;
+                if (mode === 'auto-inject' && column) {
+                    // Wrap all query builders in the context to auto-inject tenant filters
+                    const contextValues = context;
+                    for (const key of Object.keys(contextValues)) {
+                        const value = contextValues[key];
+                        // Check if it looks like a query builder (has a table method)
+                        if (value && typeof value === 'object' && 'table' in value && typeof value.table === 'function') {
+                            contextValues[key] = createTenantScope(value, { tenantId, column });
+                        }
+                    }
+                }
+                else if (mode === 'manual') {
+                    // Warn developers in manual mode to ensure they manually filter
+                    warnTenantMisconfiguration({
+                        queryKey: endpoint.key,
+                        hasTenantConfig: true,
+                        hasTenantId: true,
+                        mode: 'manual',
+                    });
+                }
+            }
+            else if (tenantConfig && !tenantRequired) {
+                // Optional tenant mode - warn if no tenant config when accessing user data
+                warnTenantMisconfiguration({
+                    queryKey: endpoint.key,
+                    hasTenantConfig: true,
+                    hasTenantId: false,
+                    mode: tenantConfig.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 defineServe = (config) => {
+    const basePath = config.basePath ?? "";
+    const router = new ServeRouter(basePath);
+    const globalMiddlewares = [
+        ...(config.middlewares ?? []),
+    ];
+    const authStrategies = ensureArray(config.auth);
+    const globalTenantConfig = config.tenant;
+    const contextFactory = config.context;
+    const hooks = (config.hooks ?? {});
+    const openapiConfig = {
+        enabled: config.openapi?.enabled ?? true,
+        path: config.openapi?.path ?? "/openapi.json",
+    };
+    const docsConfig = {
+        enabled: config.docs?.enabled ?? true,
+        path: config.docs?.path ?? "/docs",
+    };
+    const openapiPublicPath = applyBasePath(basePath, openapiConfig.path);
+    const configuredQueries = config.queries ?? {};
+    const queryEntries = {};
+    const registerQuery = (key, definition) => {
+        queryEntries[key] = createEndpoint(String(key), definition);
+    };
+    for (const key of Object.keys(configuredQueries)) {
+        registerQuery(key, configuredQueries[key]);
+    }
+    const handler = async (request) => {
+        const requestId = getRequestId(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,
+            requestId,
+            authStrategies,
+            contextFactory,
+            globalMiddlewares,
+            globalTenantConfig,
+            hooks,
+        });
+    };
+    // Track route configuration for client config extraction
+    const routeConfig = {};
+    const builder = {
+        queries: queryEntries,
+        _routeConfig: routeConfig,
+        route: (path, endpoint, options) => {
+            if (!endpoint) {
+                throw new Error("Endpoint definition is required when registering a route");
+            }
+            const method = options?.method ?? endpoint.method;
+            // Find the query key for this endpoint
+            const queryKey = Object.entries(queryEntries).find(([_, e]) => e === endpoint)?.[0];
+            if (queryKey) {
+                routeConfig[queryKey] = { method };
+            }
+            const normalizedPath = normalizeRoutePath(path);
+            const fallbackRequiresAuth = endpoint.auth
+                ? true
+                : authStrategies.length > 0
+                    ? true
+                    : undefined;
+            const requiresAuth = options?.requiresAuth ?? endpoint.metadata.requiresAuth ?? fallbackRequiresAuth;
+            const visibility = options?.visibility ?? endpoint.metadata.visibility ?? "public";
+            const metadata = {
+                ...endpoint.metadata,
+                path: normalizedPath,
+                method,
+                summary: options?.summary ?? endpoint.metadata.summary,
+                description: options?.description ?? endpoint.metadata.description,
+                tags: mergeTags(endpoint.metadata.tags, options?.tags),
+                requiresAuth,
+                visibility,
+            };
+            const middlewares = [...endpoint.middlewares, ...(options?.middlewares ?? [])];
+            const registeredEndpoint = {
+                ...endpoint,
+                method,
+                metadata,
+                middlewares,
+            };
+            router.register(registeredEndpoint);
+            return builder;
+        },
+        use: (middleware) => {
+            globalMiddlewares.push(middleware);
+            return builder;
+        },
+        useAuth: (strategy) => {
+            authStrategies.push(strategy);
+            router.markRoutesRequireAuth();
+            return builder;
+        },
+        execute: async (key, options) => {
+            const endpoint = queryEntries[key];
+            if (!endpoint) {
+                throw new Error(`No query registered for key ${String(key)}`);
+            }
+            // Build a synthetic request for direct execution
+            const request = {
+                method: endpoint.method,
+                path: options?.request?.path ?? endpoint.metadata.path ?? `/__execute/${String(key)}`,
+                query: options?.request?.query ?? {},
+                headers: options?.request?.headers ?? {},
+                body: options?.input ?? options?.request?.body,
+                raw: options?.request?.raw,
+            };
+            const requestId = getRequestId(request);
+            // Execute the endpoint directly using the shared helper
+            const response = await executeEndpoint({
+                endpoint,
+                request,
+                requestId,
+                authStrategies,
+                contextFactory,
+                globalMiddlewares,
+                globalTenantConfig,
+                hooks,
+                additionalContext: options?.context,
+            });
+            // If the response indicates an error, throw it
+            if (response.status !== 200) {
+                const errorBody = response.body;
+                const error = new Error(errorBody.error.message);
+                error.type = errorBody.error.type;
+                if (errorBody.error.details) {
+                    error.details = errorBody.error.details;
+                }
+                throw error;
+            }
+            // Return the successful response body
+            return response.body;
+        },
+        describe: () => {
+            const description = {
+                basePath: basePath || undefined,
+                queries: router.list().map(mapEndpointToToolkit),
+            };
+            return description;
+        },
+        handler,
+        start: async (options) => startNodeServer(handler, options),
+    };
+    if (openapiConfig.enabled) {
+        const openapiEndpoint = createOpenApiEndpoint(openapiConfig.path, () => router.list(), config.openapi);
+        router.register(openapiEndpoint);
+    }
+    if (docsConfig.enabled) {
+        const docsEndpoint = createDocsEndpoint(docsConfig.path, openapiPublicPath, config.docs);
+        router.register(docsEndpoint);
+    }
+    return builder;
+};
+const mapEndpointToToolkit = (endpoint) => {
+    // Use type assertion to avoid deep type instantiation issues with zodToJsonSchema
+    const inputSchema = endpoint.inputSchema
+        ? zodToJsonSchema(endpoint.inputSchema, { target: "openApi3" })
+        : undefined;
+    const outputSchema = endpoint.outputSchema
+        ? zodToJsonSchema(endpoint.outputSchema, { target: "openApi3" })
+        : undefined;
+    return {
+        key: endpoint.key,
+        path: endpoint.metadata.path,
+        method: endpoint.method,
+        summary: endpoint.metadata.summary,
+        description: endpoint.metadata.description,
+        tags: endpoint.metadata.tags,
+        visibility: endpoint.metadata.visibility,
+        requiresAuth: Boolean(endpoint.metadata.requiresAuth),
+        requiresTenant: endpoint.tenant ? (endpoint.tenant.required !== false) : undefined,
+        inputSchema,
+        outputSchema,
+        custom: endpoint.metadata.custom,
+    };
+};
+export const initServe = (options) => {
+    const { context, ...staticOptions } = options;
+    const procedure = createProcedureBuilder();
+    return {
+        procedure,
+        query: procedure,
+        queries: (definitions) => definitions,
+        define: (config) => {
+            return defineServe({
+                ...staticOptions,
+                ...config,
+                context: (context ?? {}),
+            });
+        },
+    };
+};

package/dist/tenant.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Utilities for multi-tenant query isolation
+ */
+/**
+ * Creates a tenant-scoped query builder wrapper that automatically
+ * adds WHERE clauses to filter by tenant.
+ *
+ * @example
+ * ```typescript
+ * const api = defineServe({
+ *   context: ({ auth }) => ({
+ *     db: createTenantScope(myDb, {
+ *       tenantId: auth?.tenantId,
+ *       column: 'organization_id',
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+export declare function createTenantScope<TDb extends {
+    table: (name: string) => any;
+}>(db: TDb, options: {
+    tenantId: string | null | undefined;
+    column: string;
+}): TDb;
+/**
+ * Runtime warning when tenant isolation might be misconfigured
+ */
+export declare function warnTenantMisconfiguration(options: {
+    queryKey: string;
+    hasTenantConfig: boolean;
+    hasTenantId: boolean;
+    mode?: string;
+}): void;
+//# sourceMappingURL=tenant.d.ts.map

package/dist/tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../src/tenant.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAS;IAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,CAAA;CAAE,EAC5E,EAAE,EAAE,GAAG,EACP,OAAO,EAAE;IACP,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB,GACA,GAAG,CAoBL;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,QAYA"}

package/dist/tenant.js

@@ -0,0 +1,49 @@
+/**
+ * Utilities for multi-tenant query isolation
+ */
+/**
+ * Creates a tenant-scoped query builder wrapper that automatically
+ * adds WHERE clauses to filter by tenant.
+ *
+ * @example
+ * ```typescript
+ * const api = defineServe({
+ *   context: ({ auth }) => ({
+ *     db: createTenantScope(myDb, {
+ *       tenantId: auth?.tenantId,
+ *       column: 'organization_id',
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+export function createTenantScope(db, options) {
+    if (!options.tenantId) {
+        return db;
+    }
+    const originalTable = db.table.bind(db);
+    return {
+        ...db,
+        table: (name) => {
+            const query = originalTable(name);
+            // Auto-inject tenant filter
+            if (query && typeof query.where === 'function') {
+                return query.where(options.column, '=', options.tenantId);
+            }
+            return query;
+        },
+    };
+}
+/**
+ * Runtime warning when tenant isolation might be misconfigured
+ */
+export function warnTenantMisconfiguration(options) {
+    if (!options.hasTenantConfig) {
+        console.warn(`[hypequery/serve] Query "${options.queryKey}" accesses user data but has no tenant configuration. ` +
+            `This may lead to data leaks. Add tenant config to defineServe or the query definition.`);
+    }
+    else if (options.hasTenantId && options.mode === 'manual') {
+        console.warn(`[hypequery/serve] Query "${options.queryKey}" uses manual tenant mode. ` +
+            `Ensure you manually filter queries by tenantId to prevent data leaks.`);
+    }
+}

package/dist/type-tests/builder.test-d.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const api: import("../types.js").ServeBuilder<import("../types.js").ServeEndpointMap<{
+    typedQuery: import("../types.js").ServeQueryConfig<z.ZodObject<{
+        plan: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        plan?: string | undefined;
+    }, {
+        plan?: string | undefined;
+    }>, z.ZodTypeAny, {}, import("../types.js").AuthContext, {
+        plan: string;
+    }[]>;
+}, {}, import("../types.js").AuthContext>, {}, import("../types.js").AuthContext>;
+//# sourceMappingURL=builder.test-d.d.ts.map

package/dist/type-tests/builder.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.test-d.d.ts","sourceRoot":"","sources":["../../src/type-tests/builder.test-d.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,GAAG;;;;;;;;;;iFAUd,CAAC"}