@stackwright-pro/openapi 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,634 @@
+import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+import { z } from 'zod';
+
+/**
+ * Supported OpenAPI versions
+ */
+type OpenAPIDocument = OpenAPIV3.Document | OpenAPIV3_1.Document;
+/**
+ * Configuration for OpenAPI integration in stackwright.yml
+ */
+interface OpenAPIConfig {
+    /** Name of this integration */
+    name: string;
+    /** OpenAPI spec (URL or local file path) */
+    spec: string;
+    /** Authentication configuration */
+    auth?: {
+        type: 'bearer' | 'apiKey' | 'oauth2';
+        token?: string;
+        apiKey?: string;
+    };
+    /** Collections to generate from endpoints */
+    collections?: Array<{
+        /** API endpoint path */
+        endpoint: string;
+        /** Field to use as slug/ID */
+        slug_field: string;
+        /** Optional filters */
+        filters?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Result of OpenAPI compilation
+ */
+interface OpenAPICompilationResult {
+    /** Generated Zod schemas as code */
+    schemas: string;
+    /** Generated TypeScript types */
+    types: string;
+    /** Generated CollectionProvider implementation */
+    provider: string;
+    /** Generated API client */
+    client: string;
+}
+
+interface ParseOptions {
+    /** Whether to dereference $ref (default: true) */
+    dereference?: boolean;
+    /** Whether to validate the spec (default: true) */
+    validate?: boolean;
+}
+interface ParseResult {
+    /** Parsed and normalized OpenAPI document */
+    document: OpenAPIDocument;
+    /** OpenAPI version (3.0.x or 3.1.x) */
+    version: string;
+    /** Whether the spec was dereferenced */
+    dereferenced: boolean;
+}
+/**
+ * OpenAPI spec parser and validator
+ *
+ * Handles both OpenAPI 3.0 and 3.1 specs.
+ * Can parse from URL or local file path.
+ */
+declare class OpenAPIParser {
+    /**
+     * Parse an OpenAPI specification from URL or file path
+     *
+     * @param specPath - URL or local file path to OpenAPI spec
+     * @param options - Parsing options
+     * @returns Parsed and validated OpenAPI document
+     *
+     * @example
+     * ```typescript
+     * const parser = new OpenAPIParser();
+     * const result = await parser.parse('https://api.example.com/openapi.json');
+     * console.log(`Parsed OpenAPI ${result.version}`);
+     * ```
+     */
+    parse(specPath: string, options?: ParseOptions): Promise<ParseResult>;
+    /**
+     * Detect OpenAPI version from document
+     */
+    private detectVersion;
+    /**
+     * Enhance error messages with context
+     */
+    private enhanceError;
+    /**
+     * Check if a spec path is a URL
+     */
+    static isURL(specPath: string): boolean;
+    /**
+     * Validate that a document is OpenAPI 3.x (not Swagger 2.x)
+     */
+    static isOpenAPI3(document: unknown): document is OpenAPIDocument;
+}
+
+type SchemaObject$1 = OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject;
+/**
+ * Resolves schemas from OpenAPI documents
+ *
+ * Handles extracting and normalizing schemas for code generation.
+ */
+declare class SchemaResolver {
+    private document;
+    constructor(document: OpenAPIV3.Document | OpenAPIV3_1.Document);
+    /**
+     * Get schema for a specific path and method
+     *
+     * @param path - API path (e.g., '/equipment')
+     * @param method - HTTP method (e.g., 'get')
+     * @param responseCode - Response code (default: '200')
+     * @returns Schema object or undefined
+     */
+    getResponseSchema(path: string, method: string, responseCode?: string): SchemaObject$1 | undefined;
+    /**
+     * Get all schemas defined in components
+     */
+    getAllSchemas(): Record<string, SchemaObject$1>;
+    /**
+     * Get a specific component schema by name
+     */
+    getComponentSchema(name: string): SchemaObject$1 | undefined;
+    /**
+     * Extract all endpoints from the OpenAPI document
+     */
+    getAllEndpoints(): Array<{
+        path: string;
+        method: string;
+        operationId?: string;
+        summary?: string;
+        description?: string;
+    }>;
+}
+
+type SchemaObject = OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject;
+interface ZodGenerationOptions {
+    /** Whether to make all fields optional by default */
+    optionalByDefault?: boolean;
+    /** Custom name for the generated schema */
+    schemaName?: string;
+}
+/**
+ * Generates Zod schemas from OpenAPI schema objects
+ *
+ * This is the CORE of the "mathematically proven code" value proposition.
+ * OpenAPI schemas → Zod validation = runtime safety guarantees.
+ */
+declare class ZodSchemaGenerator {
+    /**
+     * Generate a Zod schema from an OpenAPI schema object
+     *
+     * @param schema - OpenAPI schema object
+     * @param options - Generation options
+     * @returns Zod schema code as string
+     */
+    generate(schema: SchemaObject, options?: ZodGenerationOptions): string;
+    /**
+     * Convert OpenAPI schema to Zod schema code
+     */
+    private schemaToZod;
+    /**
+     * Map OpenAPI type to Zod schema
+     */
+    private schemaTypeToZod;
+    /**
+     * Handle string schemas with formats and enums
+     */
+    private stringToZod;
+    /**
+     * Handle number/integer schemas
+     */
+    private numberToZod;
+    /**
+     * Handle array schemas
+     */
+    private arrayToZod;
+    /**
+     * Handle object schemas
+     */
+    private objectToZod;
+    /**
+     * Handle allOf, anyOf, oneOf composition
+     */
+    private handleComposition;
+}
+
+interface TypeGenerationOptions {
+    /** Name for the generated type */
+    typeName?: string;
+    /** Whether to include JSDoc comments */
+    includeJsDoc?: boolean;
+}
+/**
+ * Generates TypeScript types from Zod schemas
+ *
+ * Converts runtime-validatable Zod schemas into compile-time TypeScript types.
+ */
+declare class TypeGenerator {
+    /**
+     * Generate TypeScript type definition from a Zod schema
+     *
+     * @param zodSchema - Zod schema object
+     * @param options - Generation options
+     * @returns TypeScript type definition as string
+     *
+     * @example
+     * ```typescript
+     * const schema = z.object({ name: z.string(), age: z.number() });
+     * const generator = new TypeGenerator();
+     * const typeCode = generator.generate(schema, { typeName: 'User' });
+     * // export type User = { name: string; age: number; };
+     * ```
+     */
+    generate(zodSchema: z.ZodTypeAny, options?: TypeGenerationOptions): string;
+    /**
+     * Generate type from Zod schema code string
+     *
+     * This is used when we have the schema as code (from ZodSchemaGenerator)
+     * rather than as a runtime Zod object.
+     *
+     * @param zodSchemaCode - Zod schema as TypeScript code string
+     * @param typeName - Name for the generated type
+     * @returns TypeScript type definition
+     */
+    generateFromCode(zodSchemaCode: string, typeName: string): string;
+    /**
+     * Generate multiple types from a map of Zod schemas
+     *
+     * @param schemas - Map of schema names to Zod schemas
+     * @returns Object with type definitions for each schema
+     */
+    generateMultiple(schemas: Record<string, z.ZodTypeAny>, options?: Omit<TypeGenerationOptions, 'typeName'>): Record<string, string>;
+    /**
+     * Combine multiple type definitions into a single TypeScript module
+     *
+     * @param types - Map of type names to type code
+     * @param imports - Additional imports to include
+     * @returns Complete TypeScript module code
+     */
+    createModule(types: Record<string, string>, imports?: string[]): string;
+}
+
+interface CollectionConfig {
+    /** API endpoint path */
+    endpoint: string;
+    /** Field to use as slug/ID */
+    slugField: string;
+    /** HTTP method (default: 'get') */
+    method?: string;
+    /** Collection name (defaults to sanitized endpoint) */
+    name?: string;
+}
+interface ProviderGenerationOptions {
+    /** Name for the provider class */
+    providerName?: string;
+    /** Base URL for the API */
+    baseUrl?: string;
+    /** Auth configuration */
+    auth?: {
+        type: 'bearer' | 'apiKey';
+        headerName?: string;
+    };
+}
+/**
+ * Generates CollectionProvider implementations from OpenAPI specs
+ *
+ * This is the bridge between OpenAPI APIs and Stackwright's content system.
+ */
+declare class CollectionProviderGenerator {
+    private document;
+    constructor(document: OpenAPIDocument);
+    /**
+     * Generate a CollectionProvider implementation for a specific endpoint
+     *
+     * @param config - Collection configuration
+     * @param options - Generation options
+     * @returns TypeScript code for the provider
+     */
+    generate(config: CollectionConfig, options?: ProviderGenerationOptions): string;
+    /**
+     * Generate the complete provider code
+     */
+    private generateProviderCode;
+    /**
+     * Generate get method implementation
+     */
+    private generateGetMethod;
+    /**
+     * Generate auth header code
+     */
+    private generateAuthHeader;
+    /**
+     * Get base URL from OpenAPI spec
+     */
+    private getBaseUrl;
+    /**
+     * Generate provider class name from config
+     */
+    private generateProviderName;
+    /**
+     * Sanitize path to valid identifier
+     */
+    private sanitizePath;
+    /**
+     * Capitalize string
+     */
+    private capitalize;
+    /**
+     * Guess which field might be a good title
+     */
+    private guessTitle;
+}
+
+/**
+ * Mapping of operationId to schema names
+ */
+interface SchemaMapping {
+    [operationId: string]: {
+        /** Schema name for request validation (null if no params) */
+        requestSchema: string | null;
+        /** Schema name for response validation */
+        responseSchema: string;
+    };
+}
+/**
+ * Options for client generation
+ */
+interface ClientGenerationOptions {
+    /** Name of the client class */
+    className?: string;
+    /** Whether to include JSDoc comments (default: true) */
+    includeJsDoc?: boolean;
+    /** Base URL for the API */
+    baseUrl?: string;
+    /** Whether to validate responses with Zod (default: true) */
+    validateResponses?: boolean;
+    /** Use strict validation - throw on parse errors vs safe parse (default: false) */
+    strictValidation?: boolean;
+    /** Mapping of operationId to schema names for Zod validation */
+    schemaMapping?: SchemaMapping;
+}
+/**
+ * ClientGenerator
+ *
+ * Generates fully typed API client functions from OpenAPI operations.
+ * Each endpoint becomes a type-safe function with runtime Zod validation.
+ *
+ * **Refactored to use Zod schemas as single source of truth:**
+ * - Types inferred from Zod schemas (no more manual type generation)
+ * - Request validation before API calls
+ * - Response validation after API calls
+ * - Optional strict validation mode
+ */
+declare class ClientGenerator {
+    private document;
+    private resolver;
+    private schemaMapping?;
+    private requiredSchemas;
+    constructor(document: OpenAPIDocument, schemaMapping?: SchemaMapping);
+    /**
+     * Generate typed API client code from OpenAPI document
+     */
+    generate(options?: ClientGenerationOptions): string;
+    /**
+     * Generate import statements including Zod and schemas
+     */
+    private generateImports;
+    /**
+     * Track which schemas are used for imports
+     */
+    private addRequiredSchema;
+    /**
+     * Generate Zod schemas for request parameters
+     *
+     * This generates schemas like:
+     * export const ListEquipmentRequestSchema = z.object({
+     *   query: z.object({ ... }).optional(),
+     * });
+     */
+    private generateRequestSchemas;
+    /**
+     * Generate request schema for a single endpoint
+     */
+    private generateRequestSchemaForEndpoint;
+    /**
+     * Generate Zod schema for path parameters
+     */
+    private generatePathParamsSchema;
+    /**
+     * Generate Zod schema for query parameters
+     */
+    private generateQueryParamsSchema;
+    /**
+     * Generate Zod schema for header parameters
+     */
+    private generateHeaderParamsSchema;
+    /**
+     * Generate Zod schema for request body
+     */
+    private generateRequestBodySchema;
+    /**
+     * Convert parameter schema to Zod schema string
+     */
+    private parameterSchemaToZod;
+    /**
+     * Convert OpenAPI schema object to Zod schema string
+     *
+     * This is a simplified version for parameter schemas.
+     * Reuses logic similar to ZodSchemaGenerator but outputs inline.
+     */
+    private schemaObjectToZod;
+    /**
+     * Convert string schema to Zod
+     */
+    private stringSchemaToZod;
+    /**
+     * Convert number schema to Zod
+     */
+    private numberSchemaToZod;
+    /**
+     * Check if header is a common header handled by fetch
+     */
+    private isCommonHeader;
+    /**
+     * Extract component name from $ref
+     */
+    private extractComponentName;
+    /**
+     * Escape string for use in Zod .describe()
+     */
+    private escapeString;
+    /**
+     * Get list of all required schema names
+     */
+    private getRequiredSchemas;
+    /**
+     * Generate TypeScript types for request/response
+     *
+     * If schemaMapping is provided, use z.infer<> to get types from Zod schemas.
+     * Otherwise, fall back to legacy manual type generation.
+     */
+    private generateTypes;
+    /**
+     * Generate types using Zod inference (NEW)
+     */
+    /**
+     * Generate types using Zod inference (NEW)
+     *
+     * Request types infer from request schemas (defined in this file).
+     * Response types infer from response schemas (imported from ./schemas).
+     */
+    private generateTypesFromZod;
+    /**
+     * Generate types using manual conversion (LEGACY - backward compatible)
+     */
+    private generateTypesLegacy;
+    /**
+     * Generate request type for an operation (LEGACY)
+     */
+    private generateRequestTypeLegacy;
+    /**
+     * Generate response type for an operation (LEGACY)
+     */
+    private generateResponseTypeLegacy;
+    /**
+     * Get request body type (LEGACY)
+     */
+    private getRequestBodyTypeLegacy;
+    /**
+     * Convert OpenAPI schema to TypeScript type (LEGACY)
+     *
+     * NOTE: This method is kept for backward compatibility but should be
+     * replaced with Zod inference in new code.
+     */
+    private getTypeFromSchemaLegacy;
+    /**
+     * Generate error classes for API errors and validation errors
+     */
+    /**
+     * Generate error classes (APIError and ValidationError)
+     */
+    private generateErrorClasses;
+    /**
+     * Generate the main client class
+     */
+    private generateClientClass;
+    /**
+     * Generate constructor
+     */
+    private generateConstructor;
+    /**
+     * Generate a method for an endpoint with Zod validation (NEW)
+     */
+    /**
+     * Generate a method for an endpoint with Zod validation (NEW)
+     */
+    private generateMethodWithValidation;
+    /**
+     * Generate a method for an endpoint (LEGACY)
+     */
+    private generateMethodLegacy;
+    /**
+     * Generate the request helper method
+     */
+    private generateRequestHelper;
+    /**
+     * Get all endpoints from the document
+     */
+    private getAllEndpoints;
+    /**
+     * Get parameters for an operation
+     */
+    private getOperationParameters;
+    /**
+     * Check if operation has request body
+     */
+    private hasRequestBody;
+    /**
+     * Check if request body is required
+     */
+    private isRequestBodyRequired;
+    /**
+     * Get method name from endpoint
+     */
+    private getMethodName;
+    /**
+     * Get type name for operation
+     */
+    private getOperationTypeName;
+    /**
+     * Convert to camelCase
+     */
+    private camelCase;
+    /**
+     * Convert to PascalCase
+     */
+    private pascalCase;
+    /**
+     * Get default base URL from servers
+     */
+    private getDefaultBaseUrl;
+    /**
+     * Get API title
+     */
+    private getAPITitle;
+    /**
+     * Get API description
+     */
+    private getAPIDescription;
+}
+
+/**
+ * OpenAPICollectionProvider
+ *
+ * Runtime implementation of CollectionProvider for OpenAPI endpoints.
+ * This is the runtime component that actually fetches data.
+ */
+declare class OpenAPICollectionProvider {
+    private baseUrl;
+    private auth?;
+    constructor(baseUrl: string, auth?: {
+        type: string;
+        token?: string;
+        apiKey?: string;
+    } | undefined);
+    /**
+     * Fetch items from an API endpoint
+     */
+    fetchItems(endpoint: string): Promise<unknown[]>;
+    /**
+     * Fetch a single item by slug
+     */
+    fetchItem(endpoint: string, slug: string): Promise<unknown>;
+}
+
+/**
+ * Prebuild plugin types
+ * TODO: Move to @stackwright/types package when created
+ */
+interface PrebuildPluginContext {
+    /** Parsed site configuration from stackwright.yml */
+    siteConfig: Record<string, any>;
+    /** Project root directory */
+    projectRoot: string;
+}
+interface PrebuildPlugin {
+    /** Plugin name */
+    name: string;
+    /** Called before build starts */
+    beforeBuild?(context: PrebuildPluginContext): Promise<void>;
+    /** Called after build completes */
+    afterBuild?(context: PrebuildPluginContext): Promise<void>;
+}
+/**
+ * Prebuild plugin for OpenAPI integration
+ *
+ * Reads OpenAPI configuration from stackwright.yml and generates:
+ * - Zod validation schemas
+ * - TypeScript type definitions
+ * - CollectionProvider implementations
+ * - Typed API client functions
+ *
+ * All generated code is written to src/generated/{integrationName}/
+ */
+declare class OpenAPIPlugin implements PrebuildPlugin {
+    name: string;
+    beforeBuild(context: PrebuildPluginContext): Promise<void>;
+    private processIntegration;
+    private generateSchemas;
+    private generateTypes;
+    private generateProvider;
+    private generateClient;
+    private extractComponentName;
+    private getOperationTypeName;
+    private generateOperationId;
+    private getResponseSchemaName;
+    private sanitizeName;
+    private capitalize;
+}
+/**
+ * Factory function to create the plugin instance
+ *
+ * Usage in user's prebuild script:
+ * ```typescript
+ * const { createOpenAPIPlugin } = require('@stackwright-pro/openapi/prebuild');
+ * runPrebuild({ plugins: [createOpenAPIPlugin()] });
+ * ```
+ */
+declare function createOpenAPIPlugin(): PrebuildPlugin;
+
+export { type ClientGenerationOptions, ClientGenerator, type CollectionConfig, CollectionProviderGenerator, OpenAPICollectionProvider, type OpenAPICompilationResult, type OpenAPIConfig, type OpenAPIDocument, OpenAPIParser, OpenAPIPlugin, type ParseOptions, type ParseResult, type ProviderGenerationOptions, type SchemaMapping, SchemaResolver, type TypeGenerationOptions, TypeGenerator, type ZodGenerationOptions, ZodSchemaGenerator, createOpenAPIPlugin };