appos 0.3.5-0 → 0.3.7-0

package/dist/exports/api/openapi.d.mts

@@ -1,271 +0,0 @@
-import { Container } from "./container.mjs";
-import { AppContext } from "./app-context.mjs";
-import { z } from "zod";
-import { Express, Request, RequestHandler } from "ultimate-express";
-import * as _node_modules_zod_openapi_dist_components_B1DX_zYv_mjs0 from "#node_modules/zod-openapi/dist/components-B1DX_zYv.mjs";
-
-//#region src/api/openapi.d.ts
-
-/**
- * Utility type to enforce exact type matching (no extra properties).
- * This uses a tuple check to prevent objects with extra keys from being assigned.
- * Arrays are handled specially to avoid treating numeric indices as object keys.
- */
-type Exact<T, Expected> = [T] extends [Expected] ? [Expected] extends [T] ? T : T extends readonly unknown[] ? Expected extends readonly unknown[] ? T extends readonly (infer TItem)[] ? Expected extends readonly (infer ExpectedItem)[] ? readonly Exact<TItem, ExpectedItem>[] : T : T : { [K in keyof T]: K extends keyof Expected ? Exact<T[K], Expected[K]> : ["Error: unexpected key", K] } : { [K in keyof T]: K extends keyof Expected ? Exact<T[K], Expected[K]> : ["Error: unexpected key", K] } : T;
-/**
- * Response marker type for Express compatibility.
- */
-type ResponseMarker<T = unknown> = {
-  __response: true;
-  status: number;
-  data: T;
-};
-/**
- * Define typed response builders based on defined response schemas.
- */
-declare function defineTypedResponses<TResponses extends Record<number, {
-  description: string;
-  schema: z.ZodSchema;
-}>>(responses: TResponses): { [K in keyof TResponses as GetMethodName<K>]: K extends number ? TResponses[K]["schema"] extends z.ZodNull ? () => ResponseMarker<null> : <T extends z.infer<TResponses[K]["schema"]>>(data: Exact<T, z.infer<TResponses[K]["schema"]>>) => ResponseMarker<z.infer<TResponses[K]["schema"]>> : never } & {
-  status: <S extends keyof TResponses & number>(statusCode: S, data: TResponses[S]["schema"] extends z.ZodNull ? undefined : Exact<z.infer<TResponses[S]["schema"]>, z.infer<TResponses[S]["schema"]>>) => ResponseMarker;
-};
-type GetMethodName<K$1> = K$1 extends 200 ? "ok" : K$1 extends 201 ? "created" : K$1 extends 202 ? "accepted" : K$1 extends 204 ? "noContent" : K$1 extends 400 ? "badRequest" : K$1 extends 401 ? "unauthorized" : K$1 extends 403 ? "forbidden" : K$1 extends 404 ? "notFound" : K$1 extends 409 ? "conflict" : K$1 extends 422 ? "unprocessableEntity" : K$1 extends 500 ? "internalServerError" : never;
-/**
- * Handler parameters with full type safety for request inputs.
- */
-type HandlerParams<TParams extends z.ZodSchema | undefined = undefined, TQuery extends z.ZodSchema | undefined = undefined, TBody extends z.ZodSchema | undefined = undefined, THeaders extends z.ZodSchema | undefined = undefined, TResponses extends Record<number, {
-  description: string;
-  schema: z.ZodSchema;
-}> = Record<number, {
-  description: string;
-  schema: z.ZodSchema;
-}>> = {
-  ctx: AppContext;
-  body: TBody extends z.ZodSchema ? z.infer<TBody> : unknown;
-  headers: THeaders extends z.ZodSchema ? z.infer<THeaders> : Record<string, string>;
-  params: TParams extends z.ZodSchema ? z.infer<TParams> : Record<string, unknown>;
-  query: TQuery extends z.ZodSchema ? z.infer<TQuery> : Record<string, unknown>;
-  request: Request;
-  response: ReturnType<typeof defineTypedResponses<TResponses>>;
-};
-/**
- * Helper function to define an OpenAPI endpoint with full type safety.
- */
-declare function defineOpenAPIEndpoint<TParams extends z.ZodSchema | undefined = undefined, TQuery extends z.ZodSchema | undefined = undefined, TBody extends z.ZodSchema | undefined = undefined, THeaders extends z.ZodSchema | undefined = undefined, TResponses extends Record<number, {
-  description: string;
-  schema: z.ZodSchema;
-}> = Record<number, {
-  description: string;
-  schema: z.ZodSchema;
-}>>(spec: {
-  summary?: string;
-  description?: string;
-  params?: TParams;
-  query?: TQuery;
-  requestBody?: TBody;
-  headers?: THeaders;
-  responses: TResponses;
-  handler: (params: HandlerParams<TParams, TQuery, TBody, THeaders, TResponses>) => Promise<ResponseMarker>;
-}): {
-  summary?: string;
-  description?: string;
-  params?: TParams;
-  query?: TQuery;
-  requestBody?: TBody;
-  headers?: THeaders;
-  responses: TResponses;
-  handler: (params: HandlerParams<TParams, TQuery, TBody, THeaders, TResponses>) => Promise<ResponseMarker>;
-};
-/**
- * OpenAPI method specification type (for internal use).
- */
-type OpenAPIMethodSpec = {
-  summary?: string;
-  description?: string;
-  params?: z.ZodSchema;
-  query?: z.ZodSchema;
-  requestBody?: z.ZodSchema;
-  headers?: z.ZodSchema;
-  responses: Record<number, {
-    description: string;
-    schema: z.ZodSchema;
-  }>;
-  handler: (params: HandlerParams<any, any, any, any, any>) => Promise<ResponseMarker>;
-};
-/**
- * Configuration object for defineOpenApi.
- */
-type DefineOpenAPIConfig = { [K in "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE"]?: OpenAPIMethodSpec };
-/**
- * OpenAPI configuration for document-level settings
- */
-type OpenAPIObjectConfigV31 = {
-  info: {
-    title: string;
-    version: string;
-    description?: string;
-    contact?: {
-      name?: string;
-      email?: string;
-      url?: string;
-    };
-    license?: {
-      name: string;
-      url?: string;
-    };
-  };
-  servers?: Array<{
-    url: string;
-    description?: string;
-  }>;
-  openapi: "3.1.0";
-};
-/**
- * Simplified config input for defineOpenAPIConfig
- */
-type DefineOpenAPIConfigInput = {
-  info: OpenAPIObjectConfigV31["info"];
-  servers?: OpenAPIObjectConfigV31["servers"];
-};
-/**
- * OpenAPI registration format (without path - CLI will add it)
- */
-type OpenAPIRegistration = {
-  method: "get" | "post" | "put" | "patch" | "delete" | "head";
-  summary?: string;
-  description?: string;
-  request?: {
-    params?: z.ZodSchema;
-    query?: z.ZodSchema;
-    body?: z.ZodSchema;
-    headers?: z.ZodSchema;
-  };
-  responses: Record<number, {
-    description: string;
-    content: {
-      "application/json": {
-        schema: z.ZodSchema;
-      };
-    };
-  }>;
-};
-/**
- * Return type for defineOpenAPI function
- */
-type DefineOpenAPIReturn = {
-  handlers: Record<string, RequestHandler>;
-  openAPISpec: OpenAPIRegistration[];
-};
-/**
- * RFC 9457 compliant validation error response
- */
-type ValidationErrorResponse = {
-  error: "validation_error";
-  status: number;
-  detail: string;
-  errors: Array<{
-    field: string;
-    message: string;
-    received: unknown;
-  }>;
-};
-/**
- * Define OpenAPI-based route handlers with full type safety.
- *
- * @param config Configuration object with HTTP method specifications
- * @returns Object containing Express handlers and openAPISpec
- *
- * @example
- * ```typescript
- * // Basic usage
- * export default defineOpenAPI({
- *   GET: {
- *     summary: "Get user by ID",
- *     params: z.object({ id: z.uuid() }),
- *     responses: {
- *       200: { description: "User data", schema: UserSchema }
- *     },
- *     handler: async ({ params, response }) => {
- *       const user = await getUser(params.id);
- *       return response.ok(user); // Fully typed!
- *     }
- *   },
- *   POST: {
- *     summary: "Create user",
- *     requestBody: CreateUserSchema,
- *     responses: {
- *       201: { description: "User created", schema: UserSchema }
- *     },
- *     handler: async ({ body, response }) => {
- *       const user = await createUser(body);
- *       return response.created(user); // Fully typed!
- *     }
- *   }
- * });
- * ```
- */
-declare function defineOpenAPI(config: DefineOpenAPIConfig): DefineOpenAPIReturn;
-/**
- * Define OpenAPI document configuration with improved DX.
- *
- * Only allows specifying info and servers objects, ensuring a consistent
- * OpenAPI v3.1.0 structure while preventing configuration of other fields.
- *
- * @param config Configuration object with info and optional servers
- * @returns Complete OpenAPI configuration object
- *
- * @example
- * ```typescript
- * export const openAPIConfig = defineOpenAPIConfig({
- *   info: {
- *     title: "My API",
- *     version: "1.0.0",
- *     description: "API v1 - Authentication and core features",
- *     contact: {
- *       name: "API Support",
- *       email: "support@example.com",
- *     },
- *   },
- *   servers: [
- *     {
- *       url: process.env.API_URL || "http://localhost:8000",
- *       description: "API Server",
- *     },
- *   ],
- * });
- * ```
- */
-declare function defineOpenAPIConfig<TContainer extends Container = Container>(config: (container: TContainer) => DefineOpenAPIConfigInput): (container: TContainer) => OpenAPIObjectConfigV31;
-/**
- * Route module type for scanned API routes
- */
-type RouteModule = {
-  path: string;
-  filePath: string;
-  handlers: Record<string, RequestHandler>;
-  openAPISpec: OpenAPIRegistration[];
-  version?: string;
-};
-/**
- * Generate complete OpenAPI 3.1.0 document from routes using zod-openapi
- */
-declare function generateOpenAPIDocument(routes: RouteModule[], version: string, config?: DefineOpenAPIConfigInput): _node_modules_zod_openapi_dist_components_B1DX_zYv_mjs0.it;
-/**
- * Scan routes directory and convert to Express route paths using remix-flat-routes.
- */
-declare function scanAPIRoutes(container: Container): Promise<RouteModule[]>;
-/**
- * Register scanned routes with Express app.
- */
-declare function registerRoutes(app: Express, routes: RouteModule[]): void;
-/**
- * Write OpenAPI specs to api/public/openapi directory.
- */
-declare function writeOpenAPISpecs<TContainer extends Container>(container: TContainer, routes: RouteModule[]): Promise<void>;
-/**
- * Load and register API routes with Express (convenience function).
- * Also auto-generates OpenAPI specs in development mode.
- */
-declare function loadAndRegisterAPIRoutes<TContainer extends Container>(app: Express): Promise<void>;
-//#endregion
-export { DefineOpenAPIConfig, DefineOpenAPIConfigInput, DefineOpenAPIReturn, HandlerParams, OpenAPIMethodSpec, OpenAPIObjectConfigV31, OpenAPIRegistration, RouteModule, ValidationErrorResponse, defineOpenAPI, defineOpenAPIConfig, defineOpenAPIEndpoint, defineTypedResponses, generateOpenAPIDocument, loadAndRegisterAPIRoutes, registerRoutes, scanAPIRoutes, writeOpenAPISpecs };