Type Reference

/**
 * Options for initializing a Client connection
 */
interface ClientOptions {
  /** HuggingFace authentication token */
  hf_token?: `hf_${string}`;
  /** Callback for space status updates */
  status_callback?: SpaceStatusCallback | null;
  /** Basic authentication credentials [username, password] */
  auth?: [string, string] | null;
  /** Whether to include null state values in responses */
  with_null_state?: boolean;
  /** Event types to subscribe to */
  events?: EventType[];
  /** Custom HTTP headers to include with requests */
  headers?: Record<string, string>;
  /** Query parameters to include with requests */
  query_params?: Record<string, string>;
  /** Session hash for connection identification */
  session_hash?: string;
}

/**
 * Options for duplicating HuggingFace Spaces
 */
interface DuplicateOptions extends ClientOptions {
  /** Hardware tier for the duplicated space */
  hardware?: 
    | "cpu-basic" 
    | "cpu-upgrade" 
    | "t4-small" 
    | "t4-medium" 
    | "a10g-small" 
    | "a10g-large" 
    | "a100-large";
  /** Timeout for space duplication in milliseconds */
  timeout?: number;
  /** Whether to make the duplicated space private */
  private?: boolean;
}

/**
 * Gradio application configuration
 */
interface Config {
  /** Application version */
  version: string;
  /** Application mode (interface/api) */
  mode: string;
  /** Application title */
  title?: string;
  /** Application description */
  description?: string;
  /** Theme configuration */
  theme?: string;
  /** Component tree structure */
  components: Component[];
  /** Dependency definitions */
  dependencies: Dependency[];
  /** Layout configuration */
  layout?: Layout;
  /** Whether authentication is enabled */
  auth_required?: boolean;
  /** Enable queue */
  enable_queue?: boolean;
  /** Maximum queue size */
  max_queue_size?: number;
}

/**
 * Complete API information for a Gradio application
 */
interface ApiInfo<T = ApiData> {
  /** Array of all available endpoints */
  named_endpoints: EndpointInfo<T>[];
  /** Unnamed endpoints (indexed by number) */
  unnamed_endpoints: EndpointInfo<T>[];
}

/**
 * Information about a specific API endpoint
 */
interface EndpointInfo<T = ApiData> {
  /** Endpoint name (for named endpoints) */
  name?: string;
  /** Endpoint description */
  description?: string;
  /** Input parameter definitions */
  parameters: T[];
  /** Output return value definitions */
  returns: T[];
  /** Whether endpoint supports streaming */
  api_name?: string;
  /** Whether endpoint is cancellable */
  cancels?: number[];
  /** Endpoint index */
  id?: number;
}

/**
 * Raw API parameter/return data from server
 */
interface ApiData {
  /** Component type identifier */
  type: string;
  /** Human-readable label */
  label?: string;
  /** Example value */
  example?: any;
  /** Parameter description */
  description?: string;  
  /** Component configuration */
  component?: string;
  /** Serializer information */
  serializer?: string;
}

/**
 * JavaScript-formatted API parameter/return data
 */
interface JsApiData {
  /** JavaScript type name */
  type: string;
  /** TypeScript type definition */
  typescript_type?: string;
  /** Human-readable label */
  label?: string;
  /** Example value formatted for JavaScript */
  example?: any;
  /** Parameter description */
  description?: string;
  /** Whether parameter is optional */
  optional?: boolean;
  /** Default value */
  default?: any;
}

/**
 * All possible event types from Gradio streaming
 */
type EventType = "data" | "status" | "log" | "render";

/**
 * Union type of all possible events
 */
type GradioEvent = PayloadMessage | StatusMessage | LogMessage | RenderMessage;

/**
 * Mapping of event types to their data structures
 */
interface EventMap {
  data: PayloadMessage;
  status: StatusMessage;
  log: LogMessage;
  render: RenderMessage;
}

/**
 * Data event containing prediction results
 */
interface PayloadMessage {
  type: "data";
  /** Prediction output data */
  data: unknown[];
  /** Execution timestamp */
  time?: Date;
  /** Whether this is the final result */
  is_generating?: boolean;
}

/**
 * Status event with job progress information
 */
interface StatusMessage {
  type: "status";
  /** Current status information */
  status?: Status;
  /** Previous status */
  previous_status?: Status;
}

/**
 * Log event with text messages
 */
interface LogMessage {
  type: "log";
  /** Log message text */
  log: string;
  /** Log level */
  level?: "info" | "warning" | "error" | "debug";
  /** Timestamp */
  timestamp?: Date;
}

/**
 * Render event for UI updates
 */
interface RenderMessage {
  type: "render";
  /** Render data */
  data?: unknown;
  /** Component to update */
  component?: string;
}

/**
 * Detailed status information for operations
 */
interface Status {
  /** Current queue position */
  queue?: number;
  /** Status code */
  code?: "pending" | "processing" | "complete" | "error";
  /** Current processing stage */
  stage?: 
    | "pending"
    | "preprocessing" 
    | "running"
    | "postprocessing"
    | "complete"
    | "error";
  /** Status message */
  message?: string;
  /** Progress percentage (0-100) */
  progress?: number;
  /** Estimated time remaining in seconds */
  eta?: number;
  /** Processing start time */
  time?: Date;
  /** Success indicator */
  success?: boolean;
  /** Detailed progress data */
  progress_data?: ProgressData[];
}

/**
 * Progress information for individual processing steps
 */
interface ProgressData {
  /** Current progress index */
  index: number;
  /** Total steps */
  length: number;
  /** Step description */
  unit?: string;
  /** Progress description */
  desc?: string;
}

/**
 * HuggingFace Space status information
 */
interface SpaceStatus {
  /** Space identifier */
  id: string;
  /** Current space status */
  status: 
    | "building" 
    | "running" 
    | "error" 
    | "stopped" 
    | "paused"
    | "sleeping";
  /** Runtime information */
  runtime?: {
    stage: string;
    hardware: string;
  };
  /** Space URL */
  url?: string;
  /** Error message if status is error */
  error?: string;
}

/**
 * Callback function for space status updates
 */
type SpaceStatusCallback = (status: SpaceStatus) => void;

/**
 * Response from prediction operations
 */
interface PredictReturn {
  /** Array of output values from the prediction */
  data: unknown[];
  /** Execution duration in seconds */
  duration?: number;
  /** Average execution duration for this endpoint */
  average_duration?: number;
  /** Additional metadata */
  meta?: Record<string, any>;
}

/**
 * Async iterable with cancellation support for streaming operations
 */
interface SubmitIterable<T> extends AsyncIterable<T> {
  /** Cancel the streaming operation */
  cancel: () => Promise<void>;
}

/**
 * Response from file upload operations
 */
interface UploadResponse {
  /** Array of uploaded file information */
  files: Array<{
    /** Server-assigned file path */
    name: string;
    /** File size in bytes */
    size: number;
    /** Server URL for accessing the file */
    url?: string;
    /** Original filename */
    orig_name?: string;
    /** Whether upload completed successfully */
    is_file: boolean;
  }>;
  /** Upload session identifier */
  upload_id?: string;
  /** Error message if upload failed */
  error?: string;
}

/**
 * File data interface matching FileData class structure
 */
interface FileDataInterface {
  /** File path (for local files or server references) */
  path?: string;
  /** File URL (for remote files) */
  url?: string;
  /** Original filename */
  orig_name?: string;
  /** File size in bytes */
  size?: number;
  /** Blob data (for browser file handling) */
  blob?: Blob;
  /** Whether file should be treated as a stream */
  is_stream?: boolean;
  /** MIME type of the file */
  mime_type?: string;
  /** Alternative text description */
  alt_text?: string;
  /** Base64 encoded file content */
  b64?: string;
  /** Additional metadata */
  meta?: Record<string, any>;
}

/**
 * Internal blob reference for file processing
 */
interface BlobRef {
  /** Blob object */
  blob: Blob;
  /** Reference URL */
  url?: string;
  /** File metadata */
  meta?: Record<string, any>;
}

/**
 * Command interface for local file operations
 */
interface CommandInterface {
  /** Command type identifier */
  type: string;
  /** Command string/action */
  command: string;
  /** File metadata */
  meta: {
    path: string;
    name: string;
    orig_path: string;
  };
  /** Associated file data */
  fileData?: FileDataInterface;
}

/**
 * Submit function signature
 */
type SubmitFunction = (
  endpoint: string | number,
  data?: unknown[] | Record<string, unknown>,
  event_data?: unknown,
  trigger_id?: number | null,
  all_events?: boolean
) => SubmitIterable<GradioEvent>;

/**
 * Predict function signature  
 */
type PredictFunction = (
  endpoint: string | number,
  data?: unknown[] | Record<string, unknown>,
  event_data?: unknown
) => Promise<PredictReturn>;

/**
 * Legacy client return type (deprecated)
 */
type client_return = {
  predict: PredictFunction;
  submit: SubmitFunction;
  view_api: () => Promise<ApiInfo<JsApiData>>;
  component_server: (
    component_id: number,
    fn_name: string,
    data: unknown[]
  ) => Promise<unknown>;
};

/**
 * Base component interface
 */
interface Component {
  /** Unique component identifier */
  id: number;
  /** Component type (textbox, button, etc.) */
  type: string;
  /** Component properties */
  props: Record<string, any>;
  /** Child components */
  children?: Component[];
  /** Component value */
  value?: any;
  /** Whether component is visible */
  visible?: boolean;
  /** Whether component is interactive */
  interactive?: boolean;
}

/**
 * Layout configuration for component arrangement
 */
interface Layout {
  /** Component layout structure */
  structure: LayoutElement[];
  /** CSS styling */
  css?: string;
  /** Custom theme */
  theme?: string;
}

/**
 * Individual layout element
 */
interface LayoutElement {
  /** Element type */
  type: "column" | "row" | "tab" | "accordion" | "group";
  /** Child elements */
  children: (LayoutElement | number)[];
  /** Element properties */
  props?: Record<string, any>;
}

/**
 * Dependency definition for component interactions
 */
interface Dependency {
  /** Function identifier */
  id: number;
  /** Trigger components */
  trigger: number[];
  /** Input components */
  inputs: number[];
  /** Output components */
  outputs: number[];
  /** Trigger event type */
  trigger_mode?: "once" | "multiple" | "always_last";
  /** Whether to show progress */
  show_progress?: boolean;
  /** Whether operation is cancellable */
  cancels?: number[];
  /** Queue configuration */
  queue?: boolean | QueueConfig;
}

/**
 * Queue configuration for dependency processing
 */
interface QueueConfig {
  /** Maximum queue size */
  max_size?: number;
  /** Batch size for processing */
  batch_size?: number;
  /** Default timeout */
  default_timeout?: number;
}

/**
 * Available hardware types for HuggingFace Spaces
 */
type HardwareType = 
  | "cpu-basic"
  | "cpu-upgrade" 
  | "t4-small"
  | "t4-medium"
  | "a10g-small"
  | "a10g-large"
  | "a100-large";

/**
 * Space hardware configuration
 */
interface SpaceHardware {
  /** Hardware type */
  type: HardwareType;
  /** GPU memory in GB */
  gpu_memory?: number;
  /** CPU cores */
  cpu_cores?: number;
  /** RAM in GB */
  ram_gb?: number;
  /** Storage in GB */
  storage_gb?: number;
}

/**
 * Space configuration options
 */
interface SpaceConfig {
  /** Space visibility */
  private?: boolean;
  /** Hardware configuration */
  hardware?: HardwareType;
  /** Environment variables */
  env?: Record<string, string>;
  /** Requirements file content */
  requirements?: string[];
  /** Dockerfile content */  
  dockerfile?: string;
  /** Space secrets */
  secrets?: Record<string, string>;
}

/**
 * Gradio-specific error information
 */
interface GradioError extends Error {
  /** Error code */
  code?: string;
  /** HTTP status code */
  status?: number;
  /** Additional error details */
  details?: Record<string, any>;
  /** Original error cause */
  cause?: Error;
}

/**
 * Validation error for input parameters
 */
interface ValidationError {
  /** Parameter name */
  parameter: string;
  /** Error message */
  message: string;
  /** Expected type or format */
  expected?: string;
  /** Actual received value */
  received?: any;
}

/**
 * Connection error information
 */
interface ConnectionError extends GradioError {
  /** Connection attempt count */
  attempts?: number;
  /** Last successful connection time */
  last_connected?: Date;
  /** Reconnection strategy */
  retry_strategy?: "exponential" | "linear" | "none";
}

/**
 * Deep partial type for configuration objects
 */
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

/**
 * Exclude undefined from type
 */
type NonUndefined<T> = T extends undefined ? never : T;

/**
 * Extract promise result type
 */
type PromiseResult<T> = T extends Promise<infer R> ? R : T;

/**
 * Make specified properties required
 */
type RequiredKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;

/**
 * Union to intersection type conversion
 */
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends 
  (k: infer I) => void ? I : never;

/**
 * Timeout configuration
 */
interface TimeoutConfig {
  /** Connection timeout in milliseconds */
  connect?: number;
  /** Request timeout in milliseconds */
  request?: number;
  /** Idle timeout in milliseconds */
  idle?: number;
}

/**
 * Retry configuration
 */
interface RetryConfig {
  /** Maximum number of retry attempts */
  max_attempts?: number;
  /** Base delay between retries in milliseconds */
  base_delay?: number;
  /** Maximum delay between retries in milliseconds */
  max_delay?: number;
  /** Backoff strategy */
  strategy?: "exponential" | "linear" | "fixed";
  /** Which errors to retry on */
  retryable_errors?: string[];
}

/**
 * Protocol version enumeration
 */
enum ProtocolVersion {
  SSE_V1 = "sse_v1",
  SSE_V2 = "sse_v2", 
  SSE_V21 = "sse_v2.1",
  SSE_V3 = "sse_v3"
}

/**
 * Connection state enumeration
 */
enum ConnectionState {
  DISCONNECTED = "disconnected",
  CONNECTING = "connecting", 
  CONNECTED = "connected",
  RECONNECTING = "reconnecting",
  ERROR = "error"
}

/**
 * Queue status enumeration
 */
enum QueueStatus {
  PENDING = "pending",
  PROCESSING = "processing",
  COMPLETE = "complete",
  ERROR = "error",
  CANCELLED = "cancelled"
}

/**
 * File processing mode enumeration
 */
enum FileMode {
  UPLOAD = "upload",
  REFERENCE = "reference",
  STREAM = "stream",
  EMBED = "embed"
}

/**
 * Type guard for GradioEvent
 */
function isGradioEvent(obj: any): obj is GradioEvent {
  return obj && typeof obj === "object" && "type" in obj;
}

/**
 * Type guard for PayloadMessage
 */
function isPayloadMessage(obj: any): obj is PayloadMessage {
  return isGradioEvent(obj) && obj.type === "data";
}

/**
 * Type guard for StatusMessage  
 */
function isStatusMessage(obj: any): obj is StatusMessage {
  return isGradioEvent(obj) && obj.type === "status";
}

/**
 * Type guard for FileData
 */
function isFileData(obj: any): obj is FileDataInterface {
  return obj && typeof obj === "object" && 
    ("path" in obj || "url" in obj || "blob" in obj);
}

/**
 * Type guard for Client instance
 */
function isClient(obj: any): obj is Client {
  return obj && typeof obj.predict === "function" && 
    typeof obj.submit === "function";
}