Server and URL Management

/**
 * Get server URL with variables replaced
 * @param selected - Index of server to use (default: 0) 
 * @param variables - Server variables to substitute
 * @returns Fully resolved server URL
 */
url(selected?: number, variables?: ServerVariable): string;

// Basic usage with first server
const serverUrl = oas.url(); // "https://api.example.com"

// Use second server
const secondUrl = oas.url(1); // "https://staging.example.com"

// With variable substitution
const customUrl = oas.url(0, { region: "us-west", version: "v2" });
// Result: "https://us-west.api.example.com/v2"

/**
 * Get server variables configuration
 * @param selected - Index of server to get variables for (default: 0)
 * @returns Server variables object with enum options and defaults
 */
variables(selected?: number): ServerVariablesObject;

const variables = oas.variables(); 
// Result: { region: { default: "us", enum: ["us", "eu"] }, version: { default: "v1" } }

// Check available options
if (variables.region?.enum) {
  console.log("Available regions:", variables.region.enum);
}

/**
 * Get default variable values with user overrides
 * @param selected - Index of server to get defaults for (default: 0)
 * @returns Object with default values for each variable
 */
defaultVariables(selected?: number): ServerVariable;

// Get defaults for first server
const defaults = oas.defaultVariables();
// Result: { region: "us", version: "v1" }

// Defaults respect user context from constructor
const oasWithUser = new Oas(definition, { region: "eu" });
const userDefaults = oasWithUser.defaultVariables();
// Result: { region: "eu", version: "v1" }

/**
 * Split server URL into text and variable components
 * @param selected - Index of server to split (default: 0)
 * @returns Array of text and variable components with metadata
 */
splitUrl(selected?: number): Array<{
  key: string;
  type: 'text' | 'variable';
  value: string;
  description?: string;
  enum?: string[];
}>;

// For URL: "https://{region}.api.example.com/{version}"
const components = oas.splitUrl();
// Result: [
//   { key: "https://-0", type: "text", value: "https://" },
//   { key: "region-1", type: "variable", value: "region", enum: ["us", "eu"] },
//   { key: ".api.example.com/-2", type: "text", value: ".api.example.com/" },
//   { key: "version-3", type: "variable", value: "version" }
// ]

// Build dynamic UI
components.forEach(component => {
  if (component.type === "variable") {
    console.log(`Variable: ${component.value}, options: ${component.enum?.join(", ")}`);
  }
});

/**
 * Replace templated variables with values in a URL
 * @param url - URL string with {variable} templates
 * @param variables - Variable values to substitute (falls back to user context)
 * @returns URL with variables replaced
 */
replaceUrl(url: string, variables?: ServerVariable): string;

// Basic replacement
const url = "https://{region}.example.com/{version}/api";
const resolved = oas.replaceUrl(url, { region: "us-west", version: "v2" });
// Result: "https://us-west.example.com/v2/api"

// Fallback to user context
const oasWithUser = new Oas(definition, { region: "eu" });
const userResolved = oasWithUser.replaceUrl(url);
// Result: "https://eu.example.com/{version}/api" (partial replacement)

// Handle missing variables gracefully
const partial = oas.replaceUrl("https://{region}.example.com/{missing}", { region: "us" });
// Result: "https://us.example.com/{missing}" (missing variables remain as-is)

/**
 * Extract server variables from a concrete URL
 * @param baseUrl - Complete URL to extract variables from
 * @returns Server selection and extracted variables, or false if no match
 */
splitVariables(baseUrl: string): Servers | false;

// For servers: ["https://{region}.api.example.com/{version}"]
const extracted = oas.splitVariables("https://eu.api.example.com/v2/users");
// Result: { selected: 0, variables: { region: "eu", version: "v2" } }

if (extracted) {
  console.log(`Using server ${extracted.selected} with region: ${extracted.variables.region}`);
  
  // Reconstruct URL
  const reconstructed = oas.url(extracted.selected, extracted.variables);
  // Result: "https://eu.api.example.com/v2"
}

// No match case
const noMatch = oas.splitVariables("https://different.com/api");
// Result: false

// Complex variable handling
const serverUrl = "https://{env}-{region}.{domain}.com/{version}";

const variables = {
  env: "prod",
  region: { default: "us-east-1" }, // Object format
  domain: "api",
  version: "v1"
};

const resolved = oas.replaceUrl(serverUrl, variables);
// Result: "https://prod-us-east-1.api.com/v1"

// Handle multiple servers
const servers = definition.servers || [];
servers.forEach((server, index) => {
  console.log(`Server ${index}: ${oas.url(index)}`);
  
  const vars = oas.variables(index);
  if (Object.keys(vars).length > 0) {
    console.log(`Variables: ${Object.keys(vars).join(", ")}`);
  }
});

// These all get normalized properly
const urls = [
  "//api.example.com",    // -> https://api.example.com
  "api.example.com/",     // -> https://api.example.com
  "/api/v1",              // -> https://example.com/api/v1
  ""                      // -> https://example.com
];