pinakes/crates/pinakes-plugin-api/src/lib.rs

//! Pinakes Plugin API
//!
//! This crate defines the stable plugin interface for Pinakes.
//! Plugins can extend Pinakes by implementing one or more of the provided
//! traits.

use std::{
  collections::HashMap,
  path::{Path, PathBuf},
};

use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use thiserror::Error;

pub mod manifest;
pub mod types;
pub mod wasm;

pub use manifest::PluginManifest;
pub use types::*;
pub use wasm::host_functions;

/// Plugin API version - plugins must match this version
pub const PLUGIN_API_VERSION: &str = "1.0";

/// Result type for plugin operations
pub type PluginResult<T> = Result<T, PluginError>;

/// Errors that can occur in plugin operations
#[derive(Debug, Error, Serialize, Deserialize)]
pub enum PluginError {
  #[error("Plugin initialization failed: {0}")]
  InitializationFailed(String),

  #[error("Unsupported operation: {0}")]
  UnsupportedOperation(String),

  #[error("Invalid input: {0}")]
  InvalidInput(String),

  #[error("IO error: {0}")]
  IoError(String),

  #[error("Metadata extraction failed: {0}")]
  MetadataExtractionFailed(String),

  #[error("Thumbnail generation failed: {0}")]
  ThumbnailGenerationFailed(String),

  #[error("Search backend error: {0}")]
  SearchBackendError(String),

  #[error("Permission denied: {0}")]
  PermissionDenied(String),

  #[error("Resource limit exceeded: {0}")]
  ResourceLimitExceeded(String),

  #[error("Plugin error: {0}")]
  Other(String),
}

/// Context provided to plugins during initialization
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PluginContext {
  /// Plugin's data directory for persistent storage
  pub data_dir: PathBuf,

  /// Plugin's cache directory for temporary data
  pub cache_dir: PathBuf,

  /// Plugin configuration from manifest
  pub config: HashMap<String, serde_json::Value>,

  /// Capabilities granted to the plugin
  pub capabilities: Capabilities,
}

/// Capabilities that can be granted to plugins
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct Capabilities {
  /// Filesystem access permissions
  pub filesystem: FilesystemCapability,

  /// Network access permissions
  pub network: NetworkCapability,

  /// Environment variable access
  pub environment: EnvironmentCapability,

  /// Maximum memory usage in bytes
  pub max_memory_bytes: Option<usize>,

  /// Maximum CPU time in milliseconds
  pub max_cpu_time_ms: Option<u64>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct FilesystemCapability {
  /// Paths allowed for reading
  pub read: Vec<PathBuf>,

  /// Paths allowed for writing
  pub write: Vec<PathBuf>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct NetworkCapability {
  /// Whether network access is allowed
  pub enabled: bool,

  /// Allowed domains (if None, all domains allowed when enabled)
  pub allowed_domains: Option<Vec<String>>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct EnvironmentCapability {
  /// Whether environment variable access is allowed
  pub enabled: bool,

  /// Specific environment variables allowed (if None, all allowed when
  /// enabled)
  pub allowed_vars: Option<Vec<String>>,
}

/// Base trait that all plugins must implement
#[async_trait]
pub trait Plugin: Send + Sync {
  /// Get plugin metadata
  fn metadata(&self) -> &PluginMetadata;

  /// Initialize the plugin with provided context
  async fn initialize(&mut self, context: PluginContext) -> PluginResult<()>;

  /// Shutdown the plugin gracefully
  async fn shutdown(&mut self) -> PluginResult<()>;

  /// Get plugin health status
  async fn health_check(&self) -> PluginResult<HealthStatus>;
}

/// Plugin metadata
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PluginMetadata {
  pub id:                    String,
  pub name:                  String,
  pub version:               String,
  pub author:                String,
  pub description:           String,
  pub api_version:           String,
  pub capabilities_required: Capabilities,
}

/// Health status of a plugin
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HealthStatus {
  pub healthy: bool,
  pub message: Option<String>,
  pub metrics: HashMap<String, f64>,
}

/// Trait for plugins that provide custom media type support
#[async_trait]
pub trait MediaTypeProvider: Plugin {
  /// Get the list of media types this plugin supports
  fn supported_media_types(&self) -> Vec<MediaTypeDefinition>;

  /// Check if this plugin can handle the given file
  async fn can_handle(
    &self,
    path: &Path,
    mime_type: Option<&str>,
  ) -> PluginResult<bool>;
}

/// Definition of a custom media type
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MediaTypeDefinition {
  /// Unique identifier for this media type
  pub id: String,

  /// Display name
  pub name: String,

  /// Category (e.g., "video", "audio", "document", "image")
  pub category: String,

  /// File extensions associated with this type
  pub extensions: Vec<String>,

  /// MIME types associated with this type
  pub mime_types: Vec<String>,

  /// Icon name or path
  pub icon: Option<String>,
}

/// Trait for plugins that extract metadata from files
#[async_trait]
pub trait MetadataExtractor: Plugin {
  /// Extract metadata from a file
  async fn extract_metadata(
    &self,
    path: &Path,
  ) -> PluginResult<ExtractedMetadata>;

  /// Get the media types this extractor supports
  fn supported_types(&self) -> Vec<String>;
}

/// Metadata extracted from a file
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ExtractedMetadata {
  pub title:           Option<String>,
  pub description:     Option<String>,
  pub author:          Option<String>,
  pub created_at:      Option<String>,
  pub duration_secs:   Option<f64>,
  pub width:           Option<u32>,
  pub height:          Option<u32>,
  pub file_size_bytes: Option<u64>,
  pub codec:           Option<String>,
  pub bitrate_kbps:    Option<u32>,

  /// Custom metadata fields specific to this file type
  pub custom_fields: HashMap<String, serde_json::Value>,

  /// Tags extracted from the file
  pub tags: Vec<String>,
}

/// Trait for plugins that generate thumbnails
#[async_trait]
pub trait ThumbnailGenerator: Plugin {
  /// Generate a thumbnail for the given file
  async fn generate_thumbnail(
    &self,
    path: &Path,
    output_path: &Path,
    options: ThumbnailOptions,
  ) -> PluginResult<ThumbnailInfo>;

  /// Get the media types this generator supports
  fn supported_types(&self) -> Vec<String>;
}

/// Options for thumbnail generation
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ThumbnailOptions {
  pub width:   u32,
  pub height:  u32,
  pub quality: u8,
  pub format:  ThumbnailFormat,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ThumbnailFormat {
  Jpeg,
  Png,
  WebP,
}

/// Information about a generated thumbnail
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ThumbnailInfo {
  pub path:            PathBuf,
  pub width:           u32,
  pub height:          u32,
  pub file_size_bytes: u64,
}

/// Trait for plugins that provide custom search backends
#[async_trait]
pub trait SearchBackend: Plugin {
  /// Index a media item for search
  async fn index_item(&self, item: &SearchIndexItem) -> PluginResult<()>;

  /// Remove an item from the search index
  async fn remove_item(&self, item_id: &str) -> PluginResult<()>;

  /// Perform a search query
  async fn search(
    &self,
    query: &SearchQuery,
  ) -> PluginResult<Vec<SearchResult>>;

  /// Get search statistics
  async fn get_stats(&self) -> PluginResult<SearchStats>;
}

/// Item to be indexed for search
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchIndexItem {
  pub id:          String,
  pub title:       Option<String>,
  pub description: Option<String>,
  pub content:     Option<String>,
  pub tags:        Vec<String>,
  pub media_type:  String,
  pub metadata:    HashMap<String, serde_json::Value>,
}

/// Search query
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchQuery {
  pub query_text: String,
  pub filters:    HashMap<String, serde_json::Value>,
  pub limit:      usize,
  pub offset:     usize,
}

/// Search result
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchResult {
  pub id:         String,
  pub score:      f64,
  pub highlights: Vec<String>,
}

/// Search statistics
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchStats {
  pub total_indexed:    usize,
  pub index_size_bytes: u64,
  pub last_update:      Option<String>,
}

/// Trait for plugins that handle events
#[async_trait]
pub trait EventHandler: Plugin {
  /// Handle an event
  async fn handle_event(&self, event: &Event) -> PluginResult<()>;

  /// Get the event types this handler is interested in
  fn interested_events(&self) -> Vec<EventType>;
}

/// Event type
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub enum EventType {
  MediaImported,
  MediaUpdated,
  MediaDeleted,
  MediaTagged,
  MediaUntagged,
  CollectionCreated,
  CollectionUpdated,
  CollectionDeleted,
  ScanStarted,
  ScanCompleted,
  Custom(String),
}

/// Event data
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Event {
  pub event_type: EventType,
  pub timestamp:  String,
  pub data:       HashMap<String, serde_json::Value>,
}

/// Trait for plugins that provide UI themes
#[async_trait]
pub trait ThemeProvider: Plugin {
  /// Get available themes from this provider
  fn get_themes(&self) -> Vec<ThemeDefinition>;

  /// Load a specific theme by ID
  async fn load_theme(&self, theme_id: &str) -> PluginResult<Theme>;
}

/// Theme definition
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ThemeDefinition {
  pub id:          String,
  pub name:        String,
  pub description: String,
  pub author:      String,
  pub preview_url: Option<String>,
}

/// Theme data
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Theme {
  pub id:         String,
  pub colors:     HashMap<String, String>,
  pub fonts:      HashMap<String, String>,
  pub custom_css: Option<String>,
}