oapiex 0.1.2 → 0.2.1

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { Element, IOptionalBrowserSettings, Window } from "happy-dom";
 import { Command } from "@h3ravel/musket";
-import { Browser } from "puppeteer";
+import { Browser, Page } from "puppeteer";
 
 //#region src/types/app.d.ts
 type BrowserName = 'axios' | 'happy-dom' | 'jsdom' | 'puppeteer';
 interface UserConfig {
-  outputFormat: 'pretty' | 'json' | 'js';
+  outputFormat: 'pretty' | 'json' | 'js' | 'ts';
   outputShape: 'raw' | 'openapi';
   requestTimeout: number;
   maxRedirects: number;
@@ -123,6 +123,7 @@ interface OpenApiOperationLike {
   operationId?: string;
   parameters?: OpenApiParameterLike[];
   requestBody?: {
+    description?: string;
     required: boolean;
     content: Record<string, OpenApiMediaType>;
   };
@@ -216,12 +217,78 @@ declare class Application {
   loadHtmlSource(source: string, initial?: boolean): Promise<string>;
 }
 //#endregion
+//#region src/Commands/GenerateCommand.d.ts
+declare class GenerateCommand extends Command<Application> {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<void>;
+  /**
+   * Resolves the SDK source by either loading a pre-generated TypeScript artifact or
+   * crawling/parsing HTML documentation based on the provided options and source string.
+   *
+   * @param options The options for resolving the SDK source.
+   * @returns An object containing the OpenAPI document and the generated schema module as a string.
+   */
+  private resolveSdkSource;
+  /**
+   * Loads the SDK source from a pre-generated TypeScript artifact.
+   *
+   * @param source
+   * @returns
+   */
+  private loadSdkSourceFromTypeScriptArtifact;
+  /**
+   * Builds an OpenAPI document from the extracted operations.
+   *
+   * @param payload
+   * @returns
+   */
+  private buildOpenApiPayload;
+  private resolveTimeoutOverride;
+  /**
+   * Resolves the output directory for the generated SDK package.
+   *
+   * @param source The source string used to determine the output directory.
+   * @returns The resolved output directory path.
+   */
+  private resolveOutputDirectory;
+  private resolvePackageName;
+  private parseOutputMode;
+  private parseSignatureStyle;
+  private parseNamespaceStrategy;
+  private parseMethodStrategy;
+  /**
+   * Checks if the provided source string points to a TypeScript or JavaScript file, which is
+   * used to determine if the source should be loaded as a pre-generated artifact instead
+   * of crawling/parsing HTML documentation.
+   *
+   * @param source The source string to check.
+   * @returns True if the source is a TypeScript or JavaScript file, false otherwise.
+   */
+  private isTypeScriptArtifactSource;
+  /**
+   * Type guard to check if a value conforms to the OpenApiDocumentLike interface.
+   *
+   * @param value
+   * @returns
+   */
+  private isOpenApiDocumentLike;
+  /**
+   * Writes the generated files to the output directory, creating any necessary subdirectories.
+   *
+   * @param packageDir
+   * @param files
+   */
+  private writePackageFiles;
+}
+//#endregion
 //#region src/Commands/InitCommand.d.ts
 declare class InitCommand extends Command {
   protected signature: string;
   protected description: string;
   handle(): Promise<void>;
   buildConfigTemplate(): string;
+  buildSdkConfigTemplate(): string;
 }
 //#endregion
 //#region src/Commands/ParseCommand.d.ts
@@ -229,6 +296,7 @@ declare class ParseCommand extends Command<Application> {
   protected signature: string;
   protected description: string;
   handle(): Promise<void>;
+  resolveTimeoutOverride: (value: string, fallback: number) => number;
   buildOpenApiPayload: (payload: Awaited<ReturnType<Application["crawlReadmeOperations"]>> | ReturnType<typeof extractReadmeOperationFromHtml>) => OpenApiDocumentLike;
   saveOutputToFile: (content: string, source: string, shape: string, outputFormat: UserConfig["outputFormat"]) => Promise<string>;
 }
@@ -240,8 +308,254 @@ declare function resolveConfig(cliOverrides?: Partial<UserConfig>): Promise<User
 //#region src/Core.d.ts
 declare const isRecord: (value: unknown) => value is Record<string, unknown>;
 //#endregion
+//#region src/generator/types.d.ts
+type JsonLike = null | boolean | number | string | JsonLike[] | {
+  [key: string]: JsonLike;
+};
+type ShapeNode = {
+  kind: 'primitive';
+  type: string;
+} | {
+  kind: 'array';
+  item: ShapeNode;
+} | {
+  kind: 'object';
+  signature: string;
+  properties: ShapeProperty[];
+} | {
+  kind: 'union';
+  types: ShapeNode[];
+};
+interface ShapeProperty {
+  key: string;
+  optional: boolean;
+  shape: ShapeNode;
+}
+interface InterfaceDeclaration {
+  kind: 'interface';
+  name: string;
+  baseName: string;
+  rawShape: Extract<ShapeNode, {
+    kind: 'object';
+  }>;
+  properties: ShapeProperty[];
+}
+interface InterfaceAliasDeclaration {
+  kind: 'interface-alias';
+  name: string;
+  target: string;
+}
+interface TypeReferenceAliasDeclaration {
+  kind: 'type-alias';
+  name: string;
+  target: string;
+}
+interface ShapeAliasDeclaration {
+  kind: 'shape-alias';
+  name: string;
+  shape: ShapeNode;
+}
+type Declaration = InterfaceDeclaration | InterfaceAliasDeclaration | TypeReferenceAliasDeclaration | ShapeAliasDeclaration;
+interface GeneratorContext {
+  declarations: Declaration[];
+  declarationByName: Map<string, Declaration>;
+  nameBySignature: Map<string, string>;
+  usedNames: Set<string>;
+}
+interface SemanticModel {
+  path: string;
+  method: string;
+  name: string;
+  role: 'response' | 'responseExample' | 'input' | 'query' | 'header' | 'params';
+  shape: ShapeNode;
+  collisionSuffix: string;
+}
+interface OperationTypeRefs {
+  response: string;
+  responseExample: string;
+  input: string;
+  query: string;
+  header: string;
+  params: string;
+}
+type SdkNamespaceNamingStrategy = 'smart' | 'scoped';
+type SdkMethodNamingStrategy = 'smart' | 'operation-id';
+interface SdkNamingStrategyOptions {
+  namespaceStrategy?: SdkNamespaceNamingStrategy;
+  methodStrategy?: SdkMethodNamingStrategy;
+}
+interface SdkParameterManifest {
+  name: string;
+  accessor: string;
+  in: 'query' | 'header' | 'path';
+  required: boolean;
+  description?: string;
+}
+interface SdkOperationManifest {
+  path: string;
+  method: string;
+  methodName: string;
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  requestBodyDescription?: string;
+  responseDescription?: string;
+  responseType: string;
+  inputType: string;
+  queryType: string;
+  headerType: string;
+  paramsType: string;
+  hasBody: boolean;
+  bodyRequired: boolean;
+  pathParams: SdkParameterManifest[];
+  queryParams: SdkParameterManifest[];
+  headerParams: SdkParameterManifest[];
+}
+interface SdkGroupManifest {
+  className: string;
+  propertyName: string;
+  operations: SdkOperationManifest[];
+}
+interface SdkManifest {
+  groups: SdkGroupManifest[];
+}
+interface PayloadSchemaCandidate {
+  schema?: OpenApiSchema;
+  example?: unknown;
+}
+//#endregion
+//#region src/generator/OutputGenerator.d.ts
+declare class OutputGenerator {
+  /**
+   * Serialize the extracted payload into the desired output format, optionally
+   * generating TypeScript types when requested.
+   *
+   * @param payload The extracted payload to serialize.
+   * @param outputFormat The desired output format ('json', 'js', 'ts', 'pretty').
+   * @param rootTypeName The root type name to use when generating TypeScript types.
+   * @returns A promise that resolves to the serialized output string.
+    */
+  static serializeOutput: (payload: unknown, outputFormat: UserConfig["outputFormat"], rootTypeName?: string, typeScriptOptions?: SdkNamingStrategyOptions) => Promise<string>;
+  /**
+   * Build a safe file path for the output based on the workspace root, source
+   * identifier, desired shape, and output format.
+   *
+   * @param workspaceRoot     The root directory of the workspace.
+   * @param source            The original source identifier
+   * @param shape             The desired output shape ('raw' or 'openapi').
+   * @param outputFormat      The desired output format ('json', 'js', 'ts', 'pretty').
+   * @returns                 The constructed file path for the output.
+   */
+  static buildFilePath: (workspaceRoot: string, source: string, shape: string, outputFormat: UserConfig["outputFormat"]) => string;
+  static buildArtifactDirectory: (workspaceRoot: string, source: string, artifact: string) => string;
+  static toSafeSourceName(source: string): string;
+  /**
+   * Determine the appropriate root type name for TypeScript generation based on the desired
+   * output shape. This helps ensure that generated types are meaningful and contextually relevant.
+   *
+   * @param shape     The desired output shape ('raw' or 'openapi').
+   * @returns         The root type name to use for TypeScript generation.
+   */
+  static getRootTypeName: (shape: string) => string;
+}
+//#endregion
+//#region src/generator/SdkPackageGenerator.d.ts
+interface SdkPackageGeneratorOptions extends SdkNamingStrategyOptions {
+  outputMode?: 'runtime' | 'classes' | 'both';
+  signatureStyle?: 'flat' | 'grouped';
+  rootTypeName?: string;
+  schemaModule?: string;
+  packageName?: string;
+  packageVersion?: string;
+  packageDescription?: string;
+  sdkKitPackageName?: string;
+}
+declare class SdkPackageGenerator {
+  private typeBuilder;
+  private typeScriptGenerator;
+  generate(document: OpenApiDocumentLike, options?: SdkPackageGeneratorOptions): Record<string, string>;
+  private createOperationTypeRefs;
+  private renderBaseApi;
+  private renderApiBinder;
+  private renderApiClass;
+  private renderApiMethod;
+  private renderMethodDocComment;
+  private renderGroupedParameterDocs;
+  private renderFlatParameterDocs;
+  private renderParamDoc;
+  private describeParameterGroup;
+  private wrapDocText;
+  private renderGroupedSignature;
+  private renderFlatSignature;
+  private createTypeImportContext;
+  private rewriteTypeReference;
+  private renderFlatObjectLiteral;
+  private renderFlatHeaders;
+  private renderCoreFile;
+  private renderPackageJson;
+  private renderReadme;
+  private renderReadmeDescription;
+  private renderReadmeUsage;
+  private renderReadmeClientSnippet;
+  private renderReadmeClientBody;
+  private renderReadmeExports;
+  private pickExampleOperation;
+  private collectReadmeTypeImports;
+  private renderReadmeOperationCall;
+  private renderReadmeGroupedArgs;
+  private renderReadmeFlatArgs;
+  private renderTsconfig;
+  private renderTsdownConfig;
+  private renderVitestConfig;
+  private renderExportsTest;
+  private renderIndexFile;
+  private collectTypeIdentifiers;
+}
+//#endregion
+//#region src/generator/TypeScriptGenerator.d.ts
+declare class TypeScriptGenerator {
+  private typeBuilder;
+  private moduleRenderer;
+  /**
+   * Static helper method to generate a TypeScript module string from a generic JSON-like
+   * value, inferring types and creating type definitions as needed, using the provided root
+   * type name.
+   *
+   * @param value
+   * @param rootTypeName
+   * @returns
+   */
+  static generateModule: (value: JsonLike, rootTypeName?: string, options?: SdkNamingStrategyOptions) => string;
+  /**
+   * Generate a TypeScript module string from a generic JSON-like value, inferring types
+   * and creating type definitions as needed.
+   *
+   * @param value
+   * @param rootTypeName
+   * @returns
+   */
+  generate(value: JsonLike, rootTypeName?: string, options?: SdkNamingStrategyOptions): string;
+  /**
+   * Generate a TypeScript module string from an OpenAPI document, including type definitions
+   *
+   * @param document
+   * @param rootTypeName
+   * @returns
+   */
+  generateModule(document: OpenApiDocumentLike, rootTypeName: string, options?: SdkNamingStrategyOptions): string;
+  private generateGenericModule;
+  private isOpenApiDocumentLike;
+}
+//#endregion
 //#region src/JsonRepair.d.ts
-declare const parsePossiblyTruncatedJson: (value: string) => unknown | null;
+declare class JsonRepair {
+  static parsePossiblyTruncated: (value: string) => unknown | null;
+  private repairCommonJsonIssues;
+  private removeUnexpectedObjectTokens;
+  private insertMissingCommas;
+  private shouldInsertCommaBeforeKey;
+  private buildMissingJsonClosers;
+}
 //#endregion
 //#region src/Manager.d.ts
 interface BrowserSession {
@@ -268,38 +582,40 @@ declare const isSupportedBrowser: (value: string) => value is BrowserName;
  * @returns         A promise that resolves to the HTML content as a string.
  */
 declare const browser: (source: string, config?: UserConfig, initial?: boolean) => Promise<string>;
+declare const extractStablePageHtml: (page: Page, timeout: number, initial?: boolean, maxAttempts?: number) => Promise<string>;
 declare const mergeSsrPropsIntoRenderedHtml: (renderedHtml: string, rawHtml: string) => string;
 //#endregion
 //#region src/OpenApiTransform.d.ts
-declare const createOpenApiDocumentFromReadmeOperations: (operations: ReadmeOperation[], title?: string, version?: string) => OpenApiDocumentLike;
-declare const shouldSkipNormalizedOperation: (normalized: {
-  path: string;
-  method: string;
-  operation: OpenApiOperationLike;
-}) => boolean;
-declare const transformReadmeOperationToOpenApi: (operation: ReadmeOperation) => {
+type NormalizedOperation = {
   path: string;
   method: string;
   operation: OpenApiOperationLike;
-} | null;
-declare const shouldSkipPlaceholderOperation: (url: URL, operation: ReadmeOperation) => boolean;
-declare const decodeOpenApiPathname: (pathname: string) => string;
-declare const hasExtractedBodyParams: (params: ReadmeParameter[]) => boolean;
-declare const createParameters: (params: ReadmeParameter[]) => OpenApiOperationLike["parameters"] | undefined;
-declare const createRequestBody: (params: ReadmeParameter[], example: unknown | null, fallbackExample: unknown | null) => OpenApiOperationLike["requestBody"] | undefined;
-declare const buildRequestBodySchema: (params: ReadmeParameter[], example: unknown | null, fallbackExample: unknown | null) => OpenApiSchema;
-declare const inferSchemaFromExample: (value: unknown) => OpenApiSchema | undefined;
-declare const insertRequestBodyParam: (rootSchema: OpenApiSchema, param: ReadmeParameter) => void;
-declare const createParameter: (param: ReadmeParameter) => OpenApiParameterLike;
-declare const createParameterSchema: (param: ReadmeParameter) => OpenApiSchema;
-declare const createResponses: (schemas: ReadmeOperation["responseSchemas"], responseBodies: ReadmeResponseBody[]) => Record<string, OpenApiResponse>;
-declare const createResponseContent: (bodies: ReadmeResponseBody[]) => Record<string, OpenApiMediaType> | undefined;
-declare const inferSchemaFromBody: (body: unknown, format: ReadmeResponseBody["format"]) => OpenApiSchema | undefined;
-declare const resolveFallbackRequestBodyExample: (operation: ReadmeOperation) => unknown | null;
-declare const createExampleSchema: (value: unknown) => OpenApiSchema | null;
-declare const mergeOpenApiSchemas: (left: OpenApiSchema | null, right: OpenApiSchema | null) => OpenApiSchema | null;
-declare const buildOperationId: (method: string, path: string) => string;
-declare const isOpenApiParameterLocation: (value: ReadmeParameter["in"]) => value is OpenApiParameterLike["in"];
+};
+declare class OpenApiTransformer {
+  createDocument(operations: ReadmeOperation[], title?: string, version?: string): OpenApiDocumentLike;
+  transformOperation(operation: ReadmeOperation): NormalizedOperation | null;
+  private shouldSkipNormalizedOperation;
+  private shouldSkipPlaceholderOperation;
+  private decodeOpenApiPathname;
+  private hasExtractedBodyParams;
+  private createParameters;
+  private createRequestBody;
+  private buildRequestBodySchema;
+  private inferSchemaFromExample;
+  private insertRequestBodyParam;
+  private createParameter;
+  private createParameterSchema;
+  private createResponses;
+  private createResponseContent;
+  private inferSchemaFromBody;
+  private normalizeResponseExampleValue;
+  private resolveFallbackRequestBodyExample;
+  private createExampleSchema;
+  private mergeOpenApiSchemas;
+  private buildOperationId;
+  private isOpenApiParameterLocation;
+}
+declare const transformer: OpenApiTransformer;
 //#endregion
 //#region src/ReadmeCrawler.d.ts
 interface ReadmeCrawledOperation extends ReadmeOperation {
@@ -307,4 +623,4 @@ interface ReadmeCrawledOperation extends ReadmeOperation {
 }
 declare const resolveReadmeSidebarUrls: (operation: Pick<ReadmeOperation, "sidebarLinks">, baseUrl: string) => string[];
 //#endregion
-export { Application, AttributeQueryNode, AttributedNode, BrowserName, InitCommand, OpenApiDocumentLike, OpenApiMediaType, OpenApiOperationLike, OpenApiParameterLike, OpenApiResponse, OpenApiSchema, ParseCommand, QueryableNode, ReadmeCodeSnippet, ReadmeCrawledOperation, ReadmeNormalizedRequestExample, ReadmeOperation, ReadmeParameter, ReadmeResponseBody, ReadmeResponseSchema, ReadmeSidebarLink, TextNodeLike, UserConfig, browser, buildOperationId, buildOperationUrl, buildRequestBodySchema, createExampleSchema, createOpenApiDocumentFromReadmeOperations, createParameter, createParameterSchema, createParameters, createRequestBody, createResponseContent, createResponses, decodeOpenApiPathname, defaultConfig, defineConfig, endBrowserSession, escapeSelector, extractBalancedSegment, extractButtonText, extractCodeMirrorText, extractCodeSnippets, extractFetchBody, extractFetchHeaders, extractObjectPropertyValue, extractOperationDescription, extractOperationParametersFromOpenApi, extractParameterDescription, extractReadmeOperationFromHtml, extractReadmeOperationFromSsrProps, extractRequestCodeSnippets, extractRequestParams, extractRequestParamsFromOpenApi, extractRequestSnippetLabel, extractResponseBodies, extractResponseBodiesFromOpenApi, extractResponseContentTypes, extractResponseLabels, extractResponseSchemas, extractResponseSchemasFromOpenApi, extractSidebarLinkLabel, extractSidebarLinks, extractStringLiteralValue, findParameterRoot, flattenOpenApiSchemaProperties, getBrowserSession, globalConfig, hasExtractedBodyParams, inferParameterLocation, inferParameterLocationFromText, inferParameterPath, inferParameterType, inferSchemaFromBody, inferSchemaFromExample, insertRequestBodyParam, isOpenApiParameterLocation, isRecord, isRequiredParameter, isSupportedBrowser, loadUserConfig, mergeOpenApiSchemas, mergeReadmeOperations, mergeSsrPropsIntoRenderedHtml, normalizeCurlSnippet, normalizeFetchSnippet, normalizeRequestCodeSnippet, normalizeResponseBody, normalizeStructuredRequestBody, parseLooseStructuredValue, parsePossiblyTruncatedJson, readInputValue, readText, readTexts, resolveConfig, resolveFallbackRequestBodyExample, resolveOpenApiMediaExample, resolveParameterInput, resolveReadmeSidebarUrls, resolveSsrOperation, shouldSkipNormalizedOperation, shouldSkipPlaceholderOperation, startBrowserSession, supportedBrowsers, transformReadmeOperationToOpenApi };
+export { Application, AttributeQueryNode, AttributedNode, BrowserName, Declaration, GenerateCommand, GeneratorContext, InitCommand, InterfaceAliasDeclaration, InterfaceDeclaration, JsonLike, JsonRepair, OpenApiDocumentLike, OpenApiMediaType, OpenApiOperationLike, OpenApiParameterLike, OpenApiResponse, OpenApiSchema, OpenApiTransformer, OperationTypeRefs, OutputGenerator, ParseCommand, PayloadSchemaCandidate, QueryableNode, ReadmeCodeSnippet, ReadmeCrawledOperation, ReadmeNormalizedRequestExample, ReadmeOperation, ReadmeParameter, ReadmeResponseBody, ReadmeResponseSchema, ReadmeSidebarLink, SdkGroupManifest, SdkManifest, SdkMethodNamingStrategy, SdkNamespaceNamingStrategy, SdkNamingStrategyOptions, SdkOperationManifest, SdkPackageGenerator, SdkPackageGeneratorOptions, SdkParameterManifest, SemanticModel, ShapeAliasDeclaration, ShapeNode, ShapeProperty, TextNodeLike, TypeReferenceAliasDeclaration, TypeScriptGenerator, UserConfig, browser, buildOperationUrl, defaultConfig, defineConfig, endBrowserSession, escapeSelector, extractBalancedSegment, extractButtonText, extractCodeMirrorText, extractCodeSnippets, extractFetchBody, extractFetchHeaders, extractObjectPropertyValue, extractOperationDescription, extractOperationParametersFromOpenApi, extractParameterDescription, extractReadmeOperationFromHtml, extractReadmeOperationFromSsrProps, extractRequestCodeSnippets, extractRequestParams, extractRequestParamsFromOpenApi, extractRequestSnippetLabel, extractResponseBodies, extractResponseBodiesFromOpenApi, extractResponseContentTypes, extractResponseLabels, extractResponseSchemas, extractResponseSchemasFromOpenApi, extractSidebarLinkLabel, extractSidebarLinks, extractStablePageHtml, extractStringLiteralValue, findParameterRoot, flattenOpenApiSchemaProperties, getBrowserSession, globalConfig, inferParameterLocation, inferParameterLocationFromText, inferParameterPath, inferParameterType, isRecord, isRequiredParameter, isSupportedBrowser, loadUserConfig, mergeReadmeOperations, mergeSsrPropsIntoRenderedHtml, normalizeCurlSnippet, normalizeFetchSnippet, normalizeRequestCodeSnippet, normalizeResponseBody, normalizeStructuredRequestBody, parseLooseStructuredValue, readInputValue, readText, readTexts, resolveConfig, resolveOpenApiMediaExample, resolveParameterInput, resolveReadmeSidebarUrls, resolveSsrOperation, startBrowserSession, supportedBrowsers, transformer };