/**
 * Webhook Trigger type definitions
 *
 * These types define the contract for webhook providers that validate
 * signatures from external services (Cal.com, Fillout, Stripe, Instantly, etc.)
 *
 * Webhooks are a type of trigger - they start workflow executions
 * when external services send HTTP requests to Elevasis.
 *
 * Note: Provider IMPLEMENTATIONS live in apps/api/src/webhooks/providers/
 * This file only contains the interface contract.
 */

import type { WebhookProviderType } from '../../../platform/registry/types'

/**
 * Result of webhook signature validation
 */
export interface WebhookValidationResult {
  /** Whether the signature is valid */
  isValid: boolean
  /** Parsed payload if validation succeeded */
  payload?: unknown
  /** Error message if validation failed */
  error?: string
}

/**
 * Webhook provider interface
 *
 * Each provider implements signature validation specific to their
 * webhook format (e.g., HMAC-SHA256 for Cal.com and Fillout).
 *
 * @example
 * ```typescript
 * class CalComProvider implements WebhookProvider {
 *   readonly providerId = 'cal-com' as const
 *
 *   async validateSignature(rawBody, headers, secret) {
 *     // HMAC-SHA256 validation
 *   }
 *
 *   getEventType(payload) {
 *     return payload.triggerEvent // e.g., 'BOOKING_CREATED'
 *   }
 * }
 * ```
 */
export interface WebhookProvider {
  /** Provider identifier (e.g., 'cal-com', 'fillout', 'stripe') */
  readonly providerId: WebhookProviderType

  /**
   * Validate webhook signature and return parsed payload
   *
   * @param rawBody - Raw request body as string (before JSON parsing)
   * @param headers - Request headers (lowercase keys)
   * @param secret - Webhook signing secret from credentials
   * @returns Validation result with parsed payload or error
   */
  validateSignature(
    rawBody: string,
    headers: Record<string, string>,
    secret: string
  ): Promise<WebhookValidationResult>

  /**
   * Extract event type from validated payload
   *
   * @param payload - Parsed webhook payload (from validateSignature)
   * @returns Provider-specific event type (e.g., 'BOOKING_CREATED', 'invoice.paid')
   */
  getEventType(payload: unknown): string
}
