Operation Discovery and Analysis

/**
 * Get Operation instance for a path and method
 * @param path - OpenAPI path (e.g., "/users/{id}")
 * @param method - HTTP method
 * @param opts - Options including webhook flag
 * @returns Operation or Webhook instance
 */
operation(path: string, method: HttpMethods, opts?: { isWebhook?: boolean }): Operation;

// Get a standard operation
const getUserOp = oas.operation("/users/{id}", "get");
console.log(getUserOp.getSummary());
console.log(getUserOp.getParameters());

// Get a webhook (OpenAPI 3.1)
const webhookOp = oas.operation("newUser", "post", { isWebhook: true });
if (webhookOp.isWebhook()) {
  console.log("This is a webhook operation");
}

// Handle missing operations gracefully
const missingOp = oas.operation("/nonexistent", "get");
console.log(missingOp.getSummary()); // undefined for missing operations

/**
 * Find all operation matches for a complete URL
 * @param url - Complete URL to match against
 * @returns Object mapping paths to arrays of path matches
 */
findOperationMatches(url: string): PathMatches;

const matches = oas.findOperationMatches("https://api.example.com/users/123");

if (matches) {
  matches.forEach(match => {
    console.log(`Matched path: ${match.url.path}`);
    console.log(`Path parameters:`, match.url.slugs);
    console.log(`Original path: ${match.url.nonNormalizedPath}`);
  });
}

/**
 * Find operation by complete URL and method
 * @param url - Complete URL including origin and path
 * @param method - HTTP method to match
 * @returns Path match object or undefined if not found
 */
findOperation(url: string, method: HttpMethods): PathMatch | undefined;

const match = oas.findOperation("https://api.example.com/users/123", "get");

if (match) {
  console.log(`Found operation: ${match.url.method} ${match.url.path}`);
  console.log(`Parameters extracted:`, match.url.slugs); // { ":id": "123" }
  console.log(`Server origin: ${match.url.origin}`);
}

/**
 * Get Operation instance from complete URL and method
 * @param url - Complete URL to resolve
 * @param method - HTTP method
 * @returns Operation instance or undefined if not found
 */
getOperation(url: string, method: HttpMethods): Operation | undefined;

const operation = oas.getOperation("https://api.example.com/users/123", "get");

if (operation) {
  console.log(`Operation ID: ${operation.getOperationId()}`);
  console.log(`Summary: ${operation.getSummary()}`);
  console.log(`Required parameters: ${operation.hasRequiredParameters()}`);
  
  // Use all Operation methods
  const params = operation.getParameters();
  const security = operation.getSecurity();
  const responses = operation.getResponseStatusCodes();
}

/**
 * Find operation by operationId
 * @param id - operationId to search for (exact match, case-sensitive)
 * @returns Operation or Webhook instance, or undefined if not found
 */
getOperationById(id: string): Operation | Webhook | undefined;

// Find by explicit operationId
const getUserOp = oas.getOperationById("getUser");
if (getUserOp) {
  console.log(`Found: ${getUserOp.method.toUpperCase()} ${getUserOp.path}`);
}

// Find webhook by operationId
const webhookOp = oas.getOperationById("userCreated");
if (webhookOp?.isWebhook()) {
  console.log("Found webhook operation");
}

// Handle generated operationIds
const generatedOp = oas.getOperationById("getUsersUserId"); // Generated from GET /users/{id}

/**
 * Find operation by URL without specifying method
 * @param url - Complete URL to match
 * @returns Path match for the best matching operation
 */
findOperationWithoutMethod(url: string): PathMatch | undefined;

const match = oas.findOperationWithoutMethod("https://api.example.com/users/123");

if (match) {
  // Will find the operation with the fewest path parameters
  console.log(`Best match: ${match.url.path}`);
  console.log(`Available methods:`, Object.keys(match.operation));
}

interface Operation {
  /** Get operation summary */
  getSummary(): string;
  /** Get operation description */
  getDescription(): string;
  /** Get operation tags with metadata */
  getTags(): TagObject[];
  /** Check if operation is deprecated */
  isDeprecated(): boolean;
  /** Check if this is a webhook operation */
  isWebhook(): boolean;
}

interface Operation {
  /** Check if operation has an operationId */
  hasOperationId(): boolean;
  /** Get operationId or generate one from path and method */
  getOperationId(opts?: OperationIDGeneratorOptions): string;
}

const operation = oas.operation("/users/{id}", "get");

// Basic info
console.log(`Summary: ${operation.getSummary()}`);
console.log(`Description: ${operation.getDescription()}`);
console.log(`Deprecated: ${operation.isDeprecated()}`);

// Tags
const tags = operation.getTags();
tags.forEach(tag => {
  console.log(`Tag: ${tag.name}, Description: ${tag.description || 'N/A'}`);
});

// Operation ID
if (operation.hasOperationId()) {
  console.log(`Operation ID: ${operation.getOperationId()}`);
} else {
  console.log(`Generated ID: ${operation.getOperationId()}`);
}

interface Operation {
  /** Get primary content type for this operation */
  getContentType(): string;
  /** Check if operation uses form URL encoding */
  isFormUrlEncoded(): boolean;
  /** Check if operation uses multipart encoding */
  isMultipart(): boolean;
  /** Check if operation uses JSON */
  isJson(): boolean;
  /** Check if operation uses XML */
  isXml(): boolean;
}

const operation = oas.operation("/users", "post");

console.log(`Content type: ${operation.getContentType()}`);

// Type-specific handling
if (operation.isJson()) {
  console.log("Handle JSON payload");
} else if (operation.isFormUrlEncoded()) {
  console.log("Handle form data");
} else if (operation.isMultipart()) {
  console.log("Handle file uploads");
}

class Webhook extends Operation {
  /** OpenAPI 3.1 document reference */
  declare api: OAS31Document;
  
  /** Get summary with webhook-specific fallbacks */
  getSummary(): string;
  /** Get description with webhook-specific fallbacks */
  getDescription(): string;
}

class Callback extends Operation {
  /** Callback identifier */
  identifier: string;
  /** Parent path item schema */
  parentSchema: PathItemObject;
  
  /** Get callback identifier */
  getIdentifier(): string;
  /** Get summary with callback-specific fallbacks */
  getSummary(): string;
  /** Get description with callback-specific fallbacks */  
  getDescription(): string;
  /** Get parameters with parent parameter inheritance */
  getParameters(): ParameterObject[];
}

// Supports server variables in discovery
// Server: "https://{region}.api.example.com/{version}"
const operation = oas.getOperation("https://us.api.example.com/v1/users/123", "get");

// Handles path parameters
// Path: "/users/{userId}/orders/{orderId}"
const match = oas.findOperation("https://api.example.com/users/123/orders/456", "get");
console.log(match?.url.slugs); // { ":userId": "123", ":orderId": "456" }

// Automatically matches against all defined servers
const servers = [
  "https://api.example.com",
  "https://staging.example.com", 
  "https://{region}.example.com"
];

// Will match any of the above servers
const operation = oas.getOperation("https://staging.example.com/users/123", "get");