Plugin Interface Contracts

target:
  transport: http        # Transport plugin
  protocol: rest         # Protocol plugin
  serialization: json    # Serialization plugin

auth:
  type: bearer           # Auth plugin

interface Plugin {
  /**
   * Unique identifier for this plugin
   */
  readonly name: string;

  /**
   * Plugin category
   */
  readonly category: PluginCategory;

  /**
   * Human-readable description
   */
  readonly description: string;

  /**
   * Semantic version of the plugin
   */
  readonly version: string;
}

type PluginCategory = 'transport' | 'protocol' | 'serialization' | 'auth';

interface TransportPlugin extends Plugin {
  readonly category: 'transport';

  /**
   * Send a request and receive a response
   *
   * @param request - The prepared request
   * @param options - Transport-specific options
   * @returns The raw response
   */
  send(request: TransportRequest, options: TransportOptions): Promise<TransportResponse>;
}

interface TransportRequest {
  /**
   * Full URL including query parameters
   */
  url: string;

  /**
   * HTTP method (for HTTP-based transports)
   */
  method: string;

  /**
   * Request headers
   */
  headers: Record<string, string>;

  /**
   * Serialized request body (may be undefined)
   */
  body?: string | Buffer;
}

interface TransportOptions {
  /**
   * Request timeout in milliseconds
   */
  timeout?: number;

  /**
   * Number of retry attempts
   */
  retries?: number;

  /**
   * Base delay between retries in milliseconds
   */
  retryDelay?: number;
}

interface TransportResponse {
  /**
   * HTTP status code
   */
  status: number;

  /**
   * Status text (e.g., "OK", "Not Found")
   */
  statusText: string;

  /**
   * Response headers
   */
  headers: Record<string, string>;

  /**
   * Raw response body
   */
  body: string | Buffer;
}

interface ProtocolPlugin extends Plugin {
  readonly category: 'protocol';

  /**
   * Build a transport request from an operation definition
   *
   * @param operation - The operation to execute
   * @param params - Resolved parameter values
   * @param config - Target configuration from adapter
   * @returns A request ready for the transport plugin
   */
  buildRequest(
    operation: OperationDefinition,
    params: Record<string, unknown>,
    config: TargetConfig
  ): TransportRequest;

  /**
   * Parse a transport response into standard format
   *
   * @param response - Raw response from transport
   * @param operation - The operation that was executed
   * @returns Parsed response data
   */
  parseResponse(
    response: TransportResponse,
    operation: OperationDefinition
  ): ParsedResponse;
}

interface OperationDefinition {
  name: string;
  maps_to: string;          // e.g., "GET /repos/{owner}/{repo}"
  params?: Record<string, ParamDefinition>;
}

interface TargetConfig {
  base_url: string;
  transport: string;
  protocol: string;
  serialization: string;
}

interface ParsedResponse {
  /**
   * Whether the request was successful (2xx status)
   */
  ok: boolean;

  /**
   * HTTP status code
   */
  status: number;

  /**
   * Deserialized response data
   */
  data: unknown;

  /**
   * Error information (if not ok)
   */
  error?: {
    message: string;
    code?: string;
  };
}

interface SerializationPlugin extends Plugin {
  readonly category: 'serialization';

  /**
   * Content-Type header value for this format
   */
  readonly contentType: string;

  /**
   * Serialize data to string/buffer
   *
   * @param data - Data to serialize
   * @returns Serialized string or buffer
   */
  serialize(data: unknown): string | Buffer;

  /**
   * Deserialize string/buffer to data
   *
   * @param raw - Raw response body
   * @returns Deserialized data
   */
  deserialize(raw: string | Buffer): unknown;
}

interface AuthPlugin extends Plugin {
  readonly category: 'auth';

  /**
   * Attach authentication to a request
   *
   * @param request - Request to modify
   * @param config - Auth configuration from adapter
   * @param context - Runtime context for credential resolution
   * @returns Modified request with auth attached
   */
  authenticate(
    request: TransportRequest,
    config: AuthConfig,
    context: AuthContext
  ): TransportRequest;
}

interface AuthConfig {
  type: string;
  // Type-specific fields
  token_env?: string;      // For bearer
  header_name?: string;    // For api_key
  key_env?: string;        // For api_key
}

interface AuthContext {
  /**
   * Resolve an environment variable
   */
  getEnv(name: string): string | undefined;
}

interface PluginError extends Error {
  code: string;           // Error code
  plugin: string;         // Plugin name
  category: string;       // Plugin category
  cause?: Error;          // Underlying error
}