<?php

namespace PloverCRM\Modules\Integrations\Providers;

/**
 * Base Data Source Provider Interface
 * 
 * All data source providers (forms, e-commerce, memberships, etc.) implement this
 */
interface DataSourceProviderInterface
{
  /**
   * Get provider unique key
   * 
   * @return string
   */
  public function getKey(): string;

  /**
   * Get provider display name
   * 
   * @return string
   */
  public function getName(): string;

  /**
   * Get provider icon (emoji or URL)
   * 
   * @return string
   */
  public function getIcon(): string;

  /**
   * Get provider category
   * 
   * @return string One of: forms, ecommerce, membership, lms, webhooks
   */
  public function getCategory(): string;

  /**
   * Check if the plugin/source is available/installed
   * 
   * @return bool
   */
  public function isAvailable(): bool;

  /**
   * Get available data sources (forms, products, courses, etc.)
   * 
   * @return array Array of sources with id, title
   */
  public function getSources(): array;

  /**
   * Get fields for a specific source
   * 
   * @param string $sourceId
   * @return array Array of fields with key, label, type
   */
  public function getSourceFields(string $sourceId): array;

  /**
   * Register event listener for this provider
   * 
   * @param callable $callback Callback receives (providerKey, sourceId, eventType, data)
   * @return void
   */
  public function registerEventListener(callable $callback): void;

  /**
   * Get supported event types for this provider
   * 
   * @return array Array of event types with key, label
   */
  public function getSupportedEvents(): array;
}
