@simpleapps-com/augur-api 0.4.12 → 0.4.14

package/dist/cjs/utils/OpenApiSpecParser.d.ts

@@ -0,0 +1,252 @@
+export interface PathInfo {
+    path: string;
+    methods: string[];
+    parameters: string[];
+    operationIds: string[];
+    hasPathParams: boolean;
+    pathParams: string[];
+}
+export interface Parameter {
+    name: string;
+    in: 'query' | 'header' | 'path' | 'cookie';
+    required?: boolean;
+    schema?: Record<string, unknown>;
+    description?: string;
+}
+export interface RequestBody {
+    description?: string;
+    required?: boolean;
+    content?: Record<string, unknown>;
+}
+export interface Response {
+    description: string;
+    content?: Record<string, unknown>;
+    headers?: Record<string, unknown>;
+}
+export interface OperationDetails {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    parameters: Parameter[];
+    requestBody?: RequestBody;
+    responses: Record<string, Response>;
+    tags?: string[];
+    deprecated?: boolean;
+    method: string;
+    path: string;
+}
+export interface SearchResult {
+    path: string;
+    method: string;
+    score: number;
+    matchReason: string;
+    operation: OperationDetails;
+}
+export interface ComplexityMetrics {
+    totalPaths: number;
+    totalEndpoints: number;
+    pathsWithParameters: number;
+    uniqueParameterCount: number;
+    averageMethodsPerPath: number;
+    complexityScore: number;
+    deprecatedCount: number;
+    methodDistribution: Record<string, number>;
+}
+export interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface ClientStructureInfo {
+    path: string;
+    clientPath: string[];
+    method: string;
+    operationId?: string;
+    parameters: {
+        path: string[];
+        query: string[];
+        header: string[];
+        body?: Record<string, unknown>;
+    };
+    responseSchema?: Record<string, unknown> | null;
+}
+/**
+ * OpenAPI Specification Parser and Analyzer
+ *
+ * @fullPath utils.OpenApiSpecParser
+ * @service utility
+ * @domain openapi-parsing
+ * @discoverable true
+ * @searchTerms ["openapi", "parse", "specification", "analyze", "validate"]
+ * @commonPatterns ["Parse OpenAPI spec", "Analyze API endpoints", "Extract path information"]
+ * @workflow ["api-development", "schema-generation", "client-generation"]
+ * @prerequisites ["OpenAPI specification file or object"]
+ * @nextSteps ["Generate client code", "Create validation schemas", "Analyze API complexity"]
+ * @businessRules ["Must validate against OpenAPI 3.0/3.1 specification"]
+ * @functionalArea ["api-tooling"]
+ * @crossSite ["All microservices with OpenAPI specs"]
+ * @caching ["In-memory parsed spec caching"]
+ * @performance ["Parse once, query multiple times for best performance"]
+ */
+interface OpenApiSpec {
+    openapi: string;
+    info: Record<string, unknown>;
+    paths: Record<string, Record<string, unknown>>;
+    components?: Record<string, unknown>;
+    servers?: Array<Record<string, unknown>>;
+}
+export declare class OpenApiSpecParser {
+    private api;
+    private specPath;
+    private parsedAt;
+    /**
+     * Load and parse OpenAPI specification
+     *
+     * @param source File path, URL, or spec object
+     * @returns Parsed OpenAPI Document
+     * @throws Error if specification cannot be parsed
+     *
+     * @example
+     * ```typescript
+     * const parser = new OpenApiSpecParser();
+     * await parser.loadSpec('./openapi/vmi.json');
+     * ```
+     */
+    loadSpec(source: string | Record<string, unknown>): Promise<OpenApiSpec>;
+    /**
+     * Validate OpenAPI specification against schema
+     *
+     * @param source File path, URL, or spec object
+     * @returns Validation result with errors and warnings
+     */
+    validateSpec(source?: string | Record<string, unknown>): Promise<ValidationResult>;
+    /**
+     * Get all API paths with their methods and metadata
+     *
+     * Replaces: jq -r '.paths | to_entries[] | "\(.key): \(.value | keys | join(", "))"'
+     *
+     * @returns Array of path information objects
+     */
+    getAllPaths(): PathInfo[];
+    /**
+     * Get formatted path list (exact jq replacement)
+     *
+     * @returns Array of formatted strings like "path: GET, POST"
+     */
+    getAllPathsFormatted(): string[];
+    /**
+     * Get total number of paths
+     *
+     * Replaces: jq '.paths | keys | length'
+     *
+     * @returns Number of API paths
+     */
+    getPathCount(): number;
+    /**
+     * Get total number of endpoints (path + method combinations)
+     *
+     * @returns Total number of API endpoints
+     */
+    getEndpointCount(): number;
+    /**
+     * Get OpenAPI specification info
+     *
+     * Replaces: jq '.info'
+     *
+     * @returns OpenAPI info object or null
+     */
+    getSpecInfo(): Record<string, unknown> | null;
+    /**
+     * Get server information
+     *
+     * @returns Array of server definitions
+     */
+    getServers(): Array<Record<string, unknown>>;
+    /**
+     * Get detailed information about a specific endpoint
+     *
+     * @param path API path (e.g., "/users/{id}")
+     * @param method HTTP method (e.g., "GET")
+     * @returns Operation details or null if not found
+     */
+    getPathDetails(path: string, method: string): OperationDetails | null;
+    /**
+     * Get all operation details for all endpoints
+     *
+     * @returns Array of all operation details
+     */
+    getAllOperations(): OperationDetails[];
+    /**
+     * Find deprecated endpoints
+     *
+     * Replaces complex jq deprecated endpoint queries
+     *
+     * @returns Array of deprecated endpoint descriptions
+     */
+    getDeprecatedPaths(): string[];
+    /**
+     * Search for endpoints by functionality
+     *
+     * @param searchTerm Term to search for in paths, summaries, descriptions, etc.
+     * @returns Array of search results ranked by relevance
+     */
+    findEndpoints(searchTerm: string): SearchResult[];
+    /**
+     * Get component schemas
+     *
+     * @returns Object containing all component schemas
+     */
+    getComponentSchemas(): Record<string, Record<string, unknown>>;
+    /**
+     * Get complexity metrics for the API
+     *
+     * @returns Detailed complexity analysis
+     */
+    getComplexityMetrics(): ComplexityMetrics;
+    /**
+     * Generate client structure information for all endpoints
+     * This analyzes how each OpenAPI path should map to client method structure
+     *
+     * @returns Array of client structure mappings
+     */
+    generateClientStructure(): ClientStructureInfo[];
+    /**
+     * Validate that the API specification follows expected patterns
+     *
+     * @returns Validation result with any issues found
+     */
+    validateSpecification(): ValidationResult;
+    /**
+     * Get parsing metadata
+     *
+     * @returns Information about when the spec was parsed
+     */
+    getParsingInfo(): {
+        specPath: string | null;
+        parsedAt: Date | null;
+        api: boolean;
+    };
+    private extractMethods;
+    private extractPathParameters;
+    private extractOperationIds;
+    private calculateComplexityScore;
+    private pathToClientStructure;
+    private toCamelCase;
+    private analyzeParameters;
+    private extractResponseSchema;
+}
+/**
+ * Factory function for easy usage
+ *
+ * @returns New OpenApiSpecParser instance
+ */
+export declare const createOpenApiParser: () => OpenApiSpecParser;
+/**
+ * Utility function to parse OpenAPI spec from file path
+ *
+ * @param filePath Path to OpenAPI specification file
+ * @returns Configured parser instance
+ */
+export declare const parseOpenApiSpec: (filePath: string) => Promise<OpenApiSpecParser>;
+export {};
+//# sourceMappingURL=OpenApiSpecParser.d.ts.map

package/dist/cjs/utils/OpenApiSpecParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiSpecParser.d.ts","sourceRoot":"","sources":["../../../src/utils/OpenApiSpecParser.ts"],"names":[],"mappings":"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"}