vector-framework 1.2.2 → 1.2.3

package/src/openapi/generator.ts

@@ -1,11 +1,19 @@
 import type { RegisteredRouteDefinition } from '../core/router';
-import type { OpenAPIInfoOptions, RouteSchemaDefinition, StandardJSONSchemaCapable } from '../types';
+import { AuthKind, HttpAuthScheme, OpenApiSecuritySchemeType } from '../types';
+import type {
+  OpenAPIAuthOptions,
+  OpenAPIInfoOptions,
+  OpenAPISecurityScheme,
+  RouteSchemaDefinition,
+  StandardJSONSchemaCapable,
+} from '../types';
 
 type JsonSchema = Record<string, unknown>;
 
 export interface OpenAPIGenerationOptions {
   target: string;
   info?: OpenAPIInfoOptions;
+  auth?: OpenAPIAuthOptions;
 }
 
 export interface OpenAPIGenerationResult {
@@ -13,6 +21,119 @@ export interface OpenAPIGenerationResult {
   warnings: string[];
 }
 
+const AUTH_KIND_VALUES = new Set<string>(Object.values(AuthKind));
+const DEFAULT_SECURITY_SCHEME_NAMES: Record<AuthKind, string> = {
+  [AuthKind.ApiKey]: 'apiKeyAuth',
+  [AuthKind.HttpBasic]: 'basicAuth',
+  [AuthKind.HttpBearer]: 'bearerAuth',
+  [AuthKind.HttpDigest]: 'digestAuth',
+  [AuthKind.OAuth2]: 'oauth2Auth',
+  [AuthKind.OpenIdConnect]: 'openIdConnectAuth',
+  [AuthKind.MutualTls]: 'mutualTlsAuth',
+};
+
+function isAuthKind(value: unknown): value is AuthKind {
+  return typeof value === 'string' && AUTH_KIND_VALUES.has(value);
+}
+
+function resolveRouteAuthKind(routeAuth: unknown, defaultAuthKind: AuthKind): AuthKind | null {
+  if (routeAuth === undefined || routeAuth === false || routeAuth === null) {
+    return null;
+  }
+
+  if (routeAuth === true) {
+    return defaultAuthKind;
+  }
+
+  if (isAuthKind(routeAuth)) {
+    return routeAuth;
+  }
+
+  // Preserve runtime behavior for unexpected truthy auth values.
+  return defaultAuthKind;
+}
+
+function resolveSecuritySchemeName(kind: AuthKind, authOptions?: OpenAPIAuthOptions): string {
+  const configuredName = authOptions?.securitySchemeNames?.[kind];
+  if (typeof configuredName === 'string' && configuredName.trim().length > 0) {
+    return configuredName.trim();
+  }
+  return DEFAULT_SECURITY_SCHEME_NAMES[kind];
+}
+
+function toOpenApiSecurityScheme(kind: AuthKind): OpenAPISecurityScheme {
+  switch (kind) {
+    case AuthKind.ApiKey:
+      return {
+        type: OpenApiSecuritySchemeType.ApiKey,
+        name: 'X-API-Key',
+        in: 'header',
+      };
+    case AuthKind.HttpBasic:
+      return {
+        type: OpenApiSecuritySchemeType.Http,
+        scheme: HttpAuthScheme.Basic,
+      };
+    case AuthKind.HttpBearer:
+      return {
+        type: OpenApiSecuritySchemeType.Http,
+        scheme: HttpAuthScheme.Bearer,
+        bearerFormat: 'JWT',
+      };
+    case AuthKind.HttpDigest:
+      return {
+        type: OpenApiSecuritySchemeType.Http,
+        scheme: HttpAuthScheme.Digest,
+      };
+    case AuthKind.OAuth2:
+      return {
+        type: OpenApiSecuritySchemeType.OAuth2,
+        flows: {
+          authorizationCode: {
+            authorizationUrl: 'https://example.com/oauth/authorize',
+            tokenUrl: 'https://example.com/oauth/token',
+            scopes: {},
+          },
+        },
+      };
+    case AuthKind.OpenIdConnect:
+      return {
+        type: OpenApiSecuritySchemeType.OpenIdConnect,
+        openIdConnectUrl: 'https://example.com/.well-known/openid-configuration',
+      };
+    case AuthKind.MutualTls:
+      return {
+        type: OpenApiSecuritySchemeType.MutualTls,
+      };
+    default: {
+      const exhaustiveCheck: never = kind;
+      return exhaustiveCheck;
+    }
+  }
+}
+
+function resolveSecurityScheme(kind: AuthKind, authOptions?: OpenAPIAuthOptions): OpenAPISecurityScheme {
+  const defaultScheme = toOpenApiSecurityScheme(kind);
+  const override = authOptions?.securitySchemes?.[kind];
+  if (!override) {
+    return defaultScheme;
+  }
+
+  const merged: OpenAPISecurityScheme = {
+    ...defaultScheme,
+    ...override,
+  };
+
+  if (isRecord(defaultScheme.flows) && isRecord(override.flows)) {
+    merged.flows = {
+      ...defaultScheme.flows,
+      ...override.flows,
+    };
+  }
+
+  return merged;
+}
+
 function isJSONSchemaCapable(schema: unknown): schema is StandardJSONSchemaCapable {
   const standard = (schema as any)?.['~standard'];
   const converter = standard?.jsonSchema;
@@ -114,12 +235,89 @@ function isNoBodyResponseStatus(status: string): boolean {
 }
 
 function getResponseDescription(status: string): string {
-  if (status === '204') return 'No Content';
-  if (status === '205') return 'Reset Content';
-  if (status === '304') return 'Not Modified';
+  const knownDescriptions: Record<string, string> = {
+    '100': 'Continue',
+    '101': 'Switching Protocols',
+    '102': 'Processing',
+    '103': 'Early Hints',
+    '200': 'OK',
+    '201': 'Created',
+    '202': 'Accepted',
+    '203': 'Non-Authoritative Information',
+    '204': 'No Content',
+    '205': 'Reset Content',
+    '206': 'Partial Content',
+    '207': 'Multi-Status',
+    '208': 'Already Reported',
+    '226': 'IM Used',
+    '300': 'Multiple Choices',
+    '301': 'Moved Permanently',
+    '302': 'Found',
+    '303': 'See Other',
+    '304': 'Not Modified',
+    '305': 'Use Proxy',
+    '307': 'Temporary Redirect',
+    '308': 'Permanent Redirect',
+    '400': 'Bad Request',
+    '401': 'Unauthorized',
+    '402': 'Payment Required',
+    '403': 'Forbidden',
+    '404': 'Not Found',
+    '405': 'Method Not Allowed',
+    '406': 'Not Acceptable',
+    '407': 'Proxy Authentication Required',
+    '408': 'Request Timeout',
+    '409': 'Conflict',
+    '410': 'Gone',
+    '411': 'Length Required',
+    '412': 'Precondition Failed',
+    '413': 'Payload Too Large',
+    '414': 'URI Too Long',
+    '415': 'Unsupported Media Type',
+    '416': 'Range Not Satisfiable',
+    '417': 'Expectation Failed',
+    '418': "I'm a teapot",
+    '421': 'Misdirected Request',
+    '422': 'Unprocessable Content',
+    '423': 'Locked',
+    '424': 'Failed Dependency',
+    '425': 'Too Early',
+    '426': 'Upgrade Required',
+    '428': 'Precondition Required',
+    '429': 'Too Many Requests',
+    '431': 'Request Header Fields Too Large',
+    '451': 'Unavailable For Legal Reasons',
+    '500': 'Internal Server Error',
+    '501': 'Not Implemented',
+    '502': 'Bad Gateway',
+    '503': 'Service Unavailable',
+    '504': 'Gateway Timeout',
+    '505': 'HTTP Version Not Supported',
+    '506': 'Variant Also Negotiates',
+    '507': 'Insufficient Storage',
+    '508': 'Loop Detected',
+    '510': 'Not Extended',
+    '511': 'Network Authentication Required',
+  };
+  if (knownDescriptions[status]) {
+    return knownDescriptions[status];
+  }
+
   const numericStatus = Number(status);
   if (Number.isInteger(numericStatus) && numericStatus >= 100 && numericStatus < 200) {
-    return 'Informational';
+    return 'Informational Response';
+  }
+  if (Number.isInteger(numericStatus) && numericStatus >= 200 && numericStatus < 300) {
+    return 'Successful Response';
+  }
+  if (Number.isInteger(numericStatus) && numericStatus >= 300 && numericStatus < 400) {
+    return 'Redirection';
+  }
+  if (Number.isInteger(numericStatus) && numericStatus >= 400 && numericStatus < 500) {
+    return 'Client Error';
+  }
+  if (Number.isInteger(numericStatus) && numericStatus >= 500 && numericStatus < 600) {
+    return 'Server Error';
   }
   return 'OK';
 }
@@ -648,6 +846,8 @@ export function generateOpenAPIDocument(
 ): OpenAPIGenerationResult {
   const warnings: string[] = [];
   const paths: Record<string, Record<string, unknown>> = {};
+  const defaultAuthKind = AuthKind.HttpBearer;
+  const usedAuthKinds = new Set<AuthKind>();
 
   for (const route of routes) {
     if (route.options.expose === false) continue;
@@ -661,15 +861,64 @@ export function generateOpenAPIDocument(
       operationId: createOperationId(method, openapiPath),
       tags: [route.options.schema?.tag || inferTagFromPath(route.path)],
     };
+    if (typeof route.options.schema?.summary === 'string' && route.options.schema.summary.trim()) {
+      operation.summary = route.options.schema.summary.trim();
+    }
+    const routeSchemaDescription =
+      typeof route.options.schema?.description === 'string' && route.options.schema.description.trim()
+        ? route.options.schema.description.trim()
+        : typeof route.options.schema?.descrition === 'string' && route.options.schema.descrition.trim()
+          ? route.options.schema.descrition.trim()
+          : undefined;
+    if (routeSchemaDescription) {
+      operation.description = routeSchemaDescription;
+    }
+    if (route.options.deprecated === true) {
+      operation.deprecated = true;
+    }
+    const routeAuthKind = resolveRouteAuthKind(route.options.auth, defaultAuthKind);
+    if (routeAuthKind) {
+      usedAuthKinds.add(routeAuthKind);
+      const securitySchemeName = resolveSecuritySchemeName(routeAuthKind, options.auth);
+      operation.security = [{ [securitySchemeName]: [] }];
+    }
 
     const inputJSONSchema = convertInputSchema(route.path, route.options.schema?.input, options.target, warnings);
 
     if (inputJSONSchema) {
+      if (!operation.summary && typeof inputJSONSchema.title === 'string' && inputJSONSchema.title.trim()) {
+        operation.summary = inputJSONSchema.title.trim();
+      }
+      if (
+        !operation.description &&
+        typeof inputJSONSchema.description === 'string' &&
+        inputJSONSchema.description.trim()
+      ) {
+        operation.description = inputJSONSchema.description.trim();
+      }
       addStructuredInputToOperation(operation, inputJSONSchema);
     }
     addMissingPathParameters(operation, route.path);
 
     addOutputSchemasToOperation(operation, route.path, route.options.schema || {}, options.target, warnings);
+    if (!operation.summary || !operation.description) {
+      const responseEntries = Object.values(operation.responses || {}) as any[];
+      for (const response of responseEntries) {
+        const responseSchema = response?.content?.['application/json']?.schema;
+        if (!responseSchema || typeof responseSchema !== 'object') continue;
+        if (!operation.summary && typeof responseSchema.title === 'string' && responseSchema.title.trim()) {
+          operation.summary = responseSchema.title.trim();
+        }
+        if (
+          !operation.description &&
+          typeof responseSchema.description === 'string' &&
+          responseSchema.description.trim()
+        ) {
+          operation.description = responseSchema.description.trim();
+        }
+        if (operation.summary && operation.description) break;
+      }
+    }
 
     paths[openapiPath] ||= {};
     paths[openapiPath][method] = operation;
@@ -677,7 +926,7 @@ export function generateOpenAPIDocument(
 
   const openapiVersion = options.target === 'openapi-3.0' ? '3.0.3' : '3.1.0';
 
-  const document = {
+  const document: Record<string, unknown> = {
     openapi: openapiVersion,
     info: {
       title: options.info?.title || 'Vector API',
@@ -686,6 +935,16 @@ export function generateOpenAPIDocument(
     },
     paths,
   };
+  if (usedAuthKinds.size > 0) {
+    const securitySchemes: Record<string, OpenAPISecurityScheme> = {};
+    for (const authKind of usedAuthKinds) {
+      const name = resolveSecuritySchemeName(authKind, options.auth);
+      securitySchemes[name] = resolveSecurityScheme(authKind, options.auth);
+    }
+    document.components = {
+      securitySchemes,
+    };
+  }
 
   return {
     document,

package/src/types/index.ts

@@ -1,5 +1,6 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 } from './standard-schema';
 import type { Server } from 'bun';
+import type { CheckpointConfig } from '../checkpoint/types';
 
 // Default AuthUser type - users can override this with their own type
 export interface DefaultAuthUser {
@@ -14,7 +15,6 @@ export interface DefaultAuthUser {
 // Users can override any of these types without breaking changes
 export interface VectorTypes {
   auth?: any; // Custom auth user type
-  context?: any; // Custom request context (future)
   cache?: any; // Custom cache value type (future)
   metadata?: any; // Custom metadata type (future)
 }
@@ -22,7 +22,6 @@ export interface VectorTypes {
 // Default types
 export interface DefaultVectorTypes extends VectorTypes {
   auth: DefaultAuthUser;
-  context: Record<string, any>;
   cache: any;
   metadata: Record<string, any>;
 }
@@ -30,8 +29,6 @@ export interface DefaultVectorTypes extends VectorTypes {
 // Type helpers
 export type GetAuthType<T extends VectorTypes> = T['auth'] extends undefined ? DefaultAuthUser : T['auth'];
 
-export type GetContextType<T extends VectorTypes> = T['context'] extends undefined ? Record<string, any> : T['context'];
-
 export type GetCacheType<T extends VectorTypes> = T['cache'] extends undefined ? any : T['cache'];
 
 export type GetMetadataType<T extends VectorTypes> = T['metadata'] extends undefined
@@ -41,11 +38,7 @@ export type GetMetadataType<T extends VectorTypes> = T['metadata'] extends undef
 // Legacy support - keep AuthUser for backward compatibility
 export type AuthUser = DefaultAuthUser;
 
-type DefaultQueryShape = { [key: string]: string | string[] | undefined };
-type DefaultParamsShape = Record<string, string>;
-type DefaultCookiesShape = Record<string, string>;
-
-type BaseVectorRequest = Omit<Request, 'body' | 'json' | 'text' | 'formData' | 'arrayBuffer' | 'blob'>;
+type BaseVectorRequest = Request;
 
 type InferValidatedSection<TValidatedInput, TKey extends string, TFallback> = [TValidatedInput] extends [undefined]
   ? TFallback
@@ -56,27 +49,35 @@ type InferValidatedSection<TValidatedInput, TKey extends string, TFallback> = [T
     : TFallback;
 
 type InferValidatedInputValue<TValidatedInput> = [TValidatedInput] extends [undefined] ? unknown : TValidatedInput;
+type ValidatedInputField<TValidatedInput> = [TValidatedInput] extends [undefined]
+  ? { validatedInput?: InferValidatedInputValue<TValidatedInput> }
+  : { validatedInput: InferValidatedInputValue<TValidatedInput> };
 
 export type BunRouteHandler = (req: Request) => Response | Promise<Response>;
 export type BunMethodMap = Record<string, BunRouteHandler>;
 export type BunRouteTable = Record<string, BunMethodMap | Response>;
 export type LegacyRouteEntry = [string, RegExp, [BunRouteHandler, ...BunRouteHandler[]], string?];
 
-export interface VectorRequest<TTypes extends VectorTypes = DefaultVectorTypes, TValidatedInput = undefined>
-  extends BaseVectorRequest {
+type VectorRequestTypeBrand<TTypes extends VectorTypes, TValidatedInput> = {
+  readonly __vectorTypesBrand__?: TTypes;
+  readonly __validatedInputBrand__?: TValidatedInput;
+};
+
+export type VectorRequest<
+  TTypes extends VectorTypes = DefaultVectorTypes,
+  TValidatedInput = undefined,
+> = BaseVectorRequest & VectorRequestTypeBrand<TTypes, TValidatedInput>;
+
+export type VectorContext<TTypes extends VectorTypes = DefaultVectorTypes, TValidatedInput = undefined> = {
+  request: VectorRequest<TTypes, TValidatedInput>;
   authUser?: GetAuthType<TTypes>;
-  context: GetContextType<TTypes>;
-  metadata?: GetMetadataType<TTypes>;
+  metadata: GetMetadataType<TTypes>;
+  params: InferValidatedSection<TValidatedInput, 'params', Record<string, string>>;
+  query: InferValidatedSection<TValidatedInput, 'query', Record<string, string | string[]>>;
+  cookies: InferValidatedSection<TValidatedInput, 'cookies', Record<string, string>>;
   content?: InferValidatedSection<TValidatedInput, 'body', any>;
-  body?: InferValidatedSection<TValidatedInput, 'body', any>;
-  params?: InferValidatedSection<TValidatedInput, 'params', DefaultParamsShape>;
-  query: InferValidatedSection<TValidatedInput, 'query', DefaultQueryShape>;
-  headers: Headers;
-  cookies?: InferValidatedSection<TValidatedInput, 'cookies', DefaultCookiesShape>;
-  validatedInput?: InferValidatedInputValue<TValidatedInput>;
-  startTime?: number;
   [key: string]: any;
-}
+} & ValidatedInputField<TValidatedInput>;
 
 export interface CacheOptions {
   key?: string;
@@ -97,6 +98,52 @@ export interface RouteSchemaDefinition<
   input?: TInput;
   output?: TOutput;
   tag?: string;
+  summary?: string;
+  description?: string;
+  descrition?: string;
+}
+
+export enum OpenApiSecuritySchemeType {
+  ApiKey = 'apiKey',
+  Http = 'http',
+  MutualTls = 'mutualTLS',
+  OAuth2 = 'oauth2',
+  OpenIdConnect = 'openIdConnect',
+}
+
+export enum HttpAuthScheme {
+  Basic = 'basic',
+  Bearer = 'bearer',
+  Digest = 'digest',
+}
+
+export enum AuthKind {
+  ApiKey = 'ApiKey',
+  HttpBasic = 'HttpBasic',
+  HttpBearer = 'HttpBearer',
+  HttpDigest = 'HttpDigest',
+  OAuth2 = 'OAuth2',
+  OpenIdConnect = 'OpenIdConnect',
+  MutualTls = 'MutualTls',
+}
+
+export type RouteAuthOption = boolean | AuthKind;
+
+export interface OpenAPISecurityScheme {
+  type: OpenApiSecuritySchemeType | ({} & string);
+  description?: string;
+  name?: string;
+  in?: 'query' | 'header' | 'cookie';
+  scheme?: string;
+  bearerFormat?: string;
+  flows?: Record<string, unknown>;
+  openIdConnectUrl?: string;
+  [key: string]: unknown;
+}
+
+export interface OpenAPIAuthOptions {
+  securitySchemeNames?: Partial<Record<AuthKind, string>>;
+  securitySchemes?: Partial<Record<AuthKind, OpenAPISecurityScheme>>;
 }
 
 export type InferStandardSchemaInput<TSchema extends StandardRouteSchema> = StandardSchemaV1.InferInput<TSchema>;
@@ -113,8 +160,9 @@ export type InferRouteInputFromSchemaDefinition<TSchemaDef extends RouteSchemaDe
 export interface RouteOptions<TTypes extends VectorTypes = DefaultVectorTypes> {
   method: string;
   path: string;
-  auth?: boolean;
+  auth?: RouteAuthOption;
   expose?: boolean; // defaults to true
+  deprecated?: boolean; // OpenAPI operation.deprecated flag
   cache?: CacheOptions | number;
   rawRequest?: boolean;
   validate?: boolean; // defaults to validating schema.input unless false
@@ -125,7 +173,7 @@ export interface RouteOptions<TTypes extends VectorTypes = DefaultVectorTypes> {
 }
 
 export interface RouteBooleanDefaults {
-  auth?: boolean;
+  auth?: RouteAuthOption;
   expose?: boolean;
   rawRequest?: boolean;
   validate?: boolean;
@@ -138,7 +186,7 @@ export interface VectorDefaults {
 
 // Legacy config interface - will be deprecated
 export interface VectorConfig<TTypes extends VectorTypes = DefaultVectorTypes> {
-  port?: number;
+  port?: number | string;
   hostname?: string;
   reusePort?: boolean;
   development?: boolean;
@@ -153,6 +201,7 @@ export interface VectorConfig<TTypes extends VectorTypes = DefaultVectorTypes> {
   openapi?: OpenAPIOptions | boolean;
   startup?: StartupHandler;
   shutdown?: ShutdownHandler;
+  checkpoint?: CheckpointConfig;
 }
 
 export interface StartVectorContext {
@@ -181,7 +230,7 @@ export interface StartedVectorApp<TTypes extends VectorTypes = DefaultVectorType
 // New config-driven schema - flat structure
 export interface VectorConfigSchema<TTypes extends VectorTypes = DefaultVectorTypes> {
   // Server configuration
-  port?: number;
+  port?: number | string;
   hostname?: string;
   reusePort?: boolean;
   development?: boolean;
@@ -208,6 +257,9 @@ export interface VectorConfigSchema<TTypes extends VectorTypes = DefaultVectorTy
   startup?: StartupHandler;
   shutdown?: ShutdownHandler;
 
+  // Checkpoints
+  checkpoint?: CheckpointConfig;
+
   // Custom types for TypeScript
   types?: VectorTypes;
 }
@@ -239,15 +291,16 @@ export interface OpenAPIOptions {
   target?: 'openapi-3.0' | 'draft-2020-12' | 'draft-07' | ({} & string);
   docs?: boolean | OpenAPIDocsOptions;
   info?: OpenAPIInfoOptions;
+  auth?: OpenAPIAuthOptions;
 }
 
 export type BeforeMiddlewareHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
-  request: VectorRequest<TTypes>
-) => Promise<VectorRequest<TTypes> | Response> | VectorRequest<TTypes> | Response;
+  context: VectorContext<TTypes>
+) => Promise<void | Response> | void | Response;
 
 export type AfterMiddlewareHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
   response: Response,
-  request: VectorRequest<TTypes>
+  context: VectorContext<TTypes>
 ) => Promise<Response> | Response;
 export type MiddlewareHandler = BeforeMiddlewareHandler | AfterMiddlewareHandler;
 
@@ -255,11 +308,11 @@ export type StartupHandler = () => Promise<void> | void;
 export type ShutdownHandler = () => Promise<void> | void;
 
 export type RouteHandler<TTypes extends VectorTypes = DefaultVectorTypes, TValidatedInput = undefined> = (
-  request: VectorRequest<TTypes, TValidatedInput>
+  context: VectorContext<TTypes, TValidatedInput>
 ) => Promise<any> | any;
 
 export type ProtectedHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
-  request: VectorRequest<TTypes>
+  context: VectorContext<TTypes>
 ) => Promise<GetAuthType<TTypes>> | GetAuthType<TTypes>;
 
 export type CacheHandler = (key: string, factory: () => Promise<any>, ttl: number) => Promise<any>;

package/src/utils/validation.ts

@@ -20,16 +20,18 @@ export function validateConfig(config: VectorConfig): VectorConfig {
   return validatedConfig;
 }
 
-function validatePort(port?: number): number {
+function validatePort(port?: number | string): number {
   if (port === undefined) {
     return DEFAULT_CONFIG.PORT;
   }
 
-  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+  const normalizedPort = Number(port);
+
+  if (!Number.isInteger(normalizedPort) || normalizedPort < 1 || normalizedPort > 65535) {
     throw new Error(`Invalid port: ${port}. Port must be between 1 and 65535.`);
   }
 
-  return port;
+  return normalizedPort;
 }
 
 function validateCorsOptions(cors: CorsOptions | boolean): CorsOptions | undefined {