Programmatic API

/**
 * Creates an instance of the AutoRest engine
 * Will call initialize() with default values to bootstrap AutoRest core if necessary
 * @param logger - Logger implementation for output and diagnostics
 * @param fileSystem - File system implementation (optional, defaults to internal)
 * @param configFileOrFolderUri - URI pointing to folder or autorest configuration file
 * @returns Promise resolving to AutoRest instance
 */
function create(
  logger: IAutorestLogger,
  fileSystem?: IFileSystem,
  configFileOrFolderUri?: string
): Promise<AutoRest>;

/**
 * AutoRest class promise - resolved after core is loaded
 * Use create() function instead of accessing this directly
 */
const AutoRest: Promise<IAutoRest>;

import { create } from "autorest";
import { IAutorestLogger } from "@autorest/common";

// Basic usage with default file system
const logger: IAutorestLogger = /* your logger */;
const autorest = await create(logger);

// With custom configuration folder
const autorest = await create(
  logger,
  undefined, // use default file system
  "./config"
);

// With custom file system and config
const autorest = await create(
  logger,
  customFileSystem,
  "file:///path/to/config/autorest.md"
);

/**
 * Initializes the AutoRest-core module, bootstrapping from npm if required
 * @param logger - Logger implementation for output
 * @param requestedVersion - npm package reference for version (default: "latest-installed")
 * @param minimumVersion - semver string for minimum acceptable version
 * @returns Promise that resolves when initialization is complete
 */
function initialize(
  logger: IAutorestLogger,
  requestedVersion?: string,
  minimumVersion?: string
): Promise<void>;

/**
 * Returns the command-line application entrypoint for autorest-core
 * Bootstraps core if necessary. If initialize() was called, returns that version.
 * @param logger - Logger implementation  
 * @param requestedVersion - npm package reference (default: "latest-installed")
 * @param minimumVersion - semver minimum version string
 * @returns Promise resolving to entry point path or undefined if unavailable
 */
function getApplicationEntrypoint(
  logger: IAutorestLogger,
  requestedVersion?: string,
  minimumVersion?: string
): Promise<string | undefined>;

import { initialize, getApplicationEntrypoint } from "autorest";

// Initialize with latest installed version
await initialize(logger);

// Initialize with specific version
await initialize(logger, "3.7.0");

// Initialize with version range and minimum requirement
await initialize(logger, "^3.0.0", "3.5.0");

// Get CLI entry point after initialization
const entryPoint = await getApplicationEntrypoint(logger);
console.log(`AutoRest CLI available at: ${entryPoint}`);

/**
 * Determines if document content represents an OpenAPI specification
 * @param logger - Logger implementation
 * @param content - Document content to evaluate  
 * @returns Promise resolving to true if content is OpenAPI document
 */
function isOpenApiDocument(logger: IAutorestLogger, content: string): Promise<boolean>;

/**
 * Identifies the document type based on content analysis
 * @param logger - Logger implementation
 * @param content - Document content to analyze
 * @returns Promise resolving to identified DocumentType
 */
function identifyDocument(logger: IAutorestLogger, content: string): Promise<DocumentType>;

/**
 * Processes document (YAML, Markdown, JSON) and returns as JSON string
 * @param logger - Logger implementation  
 * @param content - Document content to convert
 * @returns Promise resolving to JSON string representation
 */
function toJSON(logger: IAutorestLogger, content: string): Promise<string>;

import { isOpenApiDocument, identifyDocument, toJSON } from "autorest";

// Check if content is OpenAPI spec
const specContent = await fs.readFile("petstore.yaml", "utf8");
const isOpenApi = await isOpenApiDocument(logger, specContent);
console.log(`Is OpenAPI: ${isOpenApi}`);

// Identify document type
const docType = await identifyDocument(logger, specContent);
console.log(`Document type: ${docType}`); // "OpenAPI2" | "OpenAPI3" | etc.

// Convert YAML spec to JSON
const yamlContent = `
openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths: {}
`;
const jsonString = await toJSON(logger, yamlContent);
const spec = JSON.parse(jsonString);

/**
 * Main AutoRest interface - actual implementation loaded dynamically from core
 * Use create() function to get instances of this interface
 */
interface AutoRest {
  /**
   * Add configuration to the AutoRest instance
   * @param config - Configuration object or settings
   */
  AddConfiguration(config: any): Promise<void>;
  
  /**
   * Process the configured specifications and generate code
   * @returns Promise resolving to generation results
   */
  Process(): Promise<GenerationResults>;
  
  // Additional methods available from dynamically loaded core
  // Exact interface depends on loaded @autorest/core version
}

/**
 * Results from AutoRest code generation process
 * Structure depends on loaded core version and generation targets
 */
interface GenerationResults {
  // Result structure varies based on core implementation
  // Typically includes generated files, messages, and metadata
}

/**
 * File system abstraction interface for AutoRest operations
 * Allows custom file system implementations for specialized scenarios
 */
interface IFileSystem {
  // Interface methods depend on core implementation
  // Used for reading specs, writing generated files, etc.
}

import { create, Channel } from "autorest";

// Create AutoRest instance and configure
const autorest = await create(logger);

// Add configuration for C# generation
await autorest.AddConfiguration({
  "input-file": "https://example.com/petstore.json",
  "output-folder": "./generated/csharp",
  "csharp": true,
  "namespace": "PetStore.Client",
  "client-name": "PetStoreClient"
});

// Process and generate code
const results = await autorest.Process();
console.log("Generation completed", results);

// Multiple configurations can be added
await autorest.AddConfiguration({
  "add-credentials": true,
  "sync-methods": "essential"
});

// Process with combined configuration
const finalResults = await autorest.Process();

/**
 * Message interface from autorest-core
 * Represents log messages, errors, and other communication from core
 */
interface Message {
  // Structure defined by @autorest/core
}

/**
 * Artifact interface from autorest-core  
 * Represents generated files and other output artifacts
 */
interface Artifact {
  // Structure defined by @autorest/core
}

/**
 * Color utility function from @autorest/common
 * Used for terminal output formatting in CLI scenarios
 */
function color(text: string): string;

/**
 * Logger interface from @autorest/common
 * Implement this interface to provide custom logging
 */
interface IAutorestLogger {
  // Methods defined by @autorest/common package
  // Used throughout AutoRest for output and diagnostics
}

import { IAutorestLogger } from "@autorest/common";
import { create } from "autorest";

// Custom logger implementation
class CustomLogger implements IAutorestLogger {
  // Implement required logger methods
  log(message: any): void {
    console.log("[AutoRest]", message);
  }
  
  // Additional methods as required by interface
}

// Use custom logger with AutoRest
const logger = new CustomLogger();
const autorest = await create(logger);

try {
  const autorest = await create(logger);
  await autorest.AddConfiguration(config);
  const results = await autorest.Process();
} catch (error) {
  console.error("AutoRest generation failed:", error);
  // Handle errors appropriately for your application
}