/**
 * DocFlow - TypeScript Type Definitions
 * 
 * A developer-friendly transformation engine built on SuperDoc
 */

// ============================================================================
// CORE TYPES
// ============================================================================

interface DocFlowConfig {
  /** Run in headless mode (default: true) */
  headless?: boolean;
  /** Validate document against schema (default: true) */
  validateSchema?: boolean;
  /** How to handle errors: 'throw' | 'collect' | 'silent' (default: 'throw') */
  errorMode?: 'throw' | 'collect' | 'silent';
}

interface DocumentInfo {
  /** File path (if loaded from file) */
  path?: string;
  /** File name */
  name?: string;
  /** Document format */
  format: 'docx' | 'html' | 'markdown' | 'json' | 'text' | 'content' | 'blank';
  /** Document buffer */
  buffer?: Buffer;
  /** Document content (if loaded as content) */
  content?: string;
}

interface Operation {
  /** Type of operation performed */
  type: 'load' | 'loadContent' | 'createBlank' | 'transform' | 'transformDocument' | 'export' | 'save' | 'clear';
  /** When the operation occurred */
  timestamp: number;
  /** Additional operation-specific data */
  [key: string]: any;
}

interface ErrorRecord {
  /** Operation that failed */
  operation: string;
  /** Error message */
  message: string;
  /** When the error occurred */
  timestamp: number;
}

interface ValidationResult {
  /** Whether the document is valid */
  valid: boolean;
  /** Array of validation errors */
  errors: string[];
  /** Array of validation warnings */
  warnings: string[];
  /** The validated document */
  document: ProseMirrorJSON;
}

// ============================================================================
// PROSEMIRROR JSON TYPES
// ============================================================================

interface ProseMirrorJSON {
  type: string;
  attrs?: Record<string, any>;
  content?: ProseMirrorJSON[];
  marks?: Mark[];
  text?: string;
}

interface Mark {
  type: string;
  attrs?: Record<string, any>;
}

interface NodeWithPath extends ProseMirrorJSON {
  /** Path to this node in the document tree */
  path: number[];
}

// ============================================================================
// QUERY TYPES
// ============================================================================

type Selector = string | PredicateFunction;

type PredicateFunction = (node: ProseMirrorJSON) => boolean;

type TransformFunction = (node: NodeWithPath) => ProseMirrorJSON | Promise<ProseMirrorJSON> | null;

type DocumentTransformFunction = (doc: ProseMirrorJSON) => ProseMirrorJSON | Promise<ProseMirrorJSON>;

// ============================================================================
// EXPORT TYPES
// ============================================================================

type ExportFormat = 'docx' | 'html' | 'markdown' | 'json' | 'text';

interface ExportOptions {
  /** Include comments in export */
  includeComments?: boolean;
  /** Include track changes in export */
  includeTrackChanges?: boolean;
  /** Custom export settings */
  [key: string]: any;
}

// ============================================================================
// BATCH PROCESSING TYPES
// ============================================================================

interface BatchProcessorConfig {
  /** Number of files to process concurrently (default: 3) */
  concurrency?: number;
  /** How to handle errors (default: 'collect') */
  errorMode?: 'throw' | 'collect' | 'silent';
}

interface BatchResult {
  /** File that was processed */
  file: string;
  /** Whether processing succeeded */
  success: boolean;
  /** Result data if successful */
  result?: any;
  /** Error if failed */
  error?: Error;
}

interface BatchSummary {
  /** Individual results */
  results: BatchResult[];
  /** Errors that occurred */
  errors: BatchResult[];
  /** Total number of files */
  total: number;
  /** Number of successful processes */
  successful: number;
  /** Number of failed processes */
  failed: number;
}

type PipelineFunction = (doc: DocFlow, file: string) => Promise<any>;

// ============================================================================
// MAIN CLASS
// ============================================================================

declare class DocFlow {
  /** Configuration options */
  readonly config: Required<DocFlowConfig>;
  
  /** Current document information */
  document?: DocumentInfo;
  
  /** Editor instance (internal) */
  editor?: any;
  
  /** Operation history */
  operations: Operation[];
  
  /** Collected errors (when errorMode is 'collect') */
  errors: ErrorRecord[];

  constructor(options?: DocFlowConfig);

  /**
   * Load a document from a FILE PATH or Buffer (NOT content strings).
   * 
   * For loading content strings (JSON, markdown, HTML), use loadContent() instead.
   * 
   * @param filePath - File path string OR Buffer object
   * @param options - Loading options
   * @throws Error if file doesn't exist or if content string is passed instead of path
   */
  load(filePath: string | Buffer, options?: { format?: ExportFormat }): Promise<DocFlow>;

  /**
   * Create a blank document without loading a DOCX file
   */
  createBlank(): Promise<DocFlow>;

  /**
   * Load content directly from a string (NOT a file path).
   * 
   * Automatically detects if content is JSON, markdown, HTML, or plain text.
   * Use this when you already have document content in memory.
   * 
   * @param content - Document content as a string (JSON/markdown/HTML/text)
   */
  loadContent(content: string): Promise<DocFlow>;

  /**
   * Get document as ProseMirror JSON
   */
  toJSON(): ProseMirrorJSON;

  /**
   * Query document structure
   */
  query(selector: Selector): QueryResult;

  /**
   * Count nodes matching selector
   */
  count(selector: Selector): number;

  /**
   * Check if document contains nodes matching selector
   */
  has(selector: Selector): boolean;

  /**
   * Get all text content from document
   */
  getText(): string;

  /**
   * Get document statistics
   */
  getStats(): {
    characters: number;
    words: number;
    paragraphs: number;
    headings: number;
    lines: number;
  };

  /**
   * Transform nodes matching selector
   */
  transform(selector: Selector, transformer: TransformFunction): Promise<DocFlow>;

  /**
   * Transform entire document
   */
  transformDocument(transformer: DocumentTransformFunction): Promise<DocFlow>;

  /**
   * Export document to format
   */
  export(format?: ExportFormat, options?: ExportOptions): Promise<Buffer | string | ProseMirrorJSON>;

  /**
   * Save document to file
   */
  save(filepath: string, format?: ExportFormat): Promise<DocFlow>;

  /**
   * Validate document against schema
   */
  validate(): ValidationResult;

  /**
   * Get operation history
   */
  getHistory(): Operation[];

  /**
   * Get collected errors (when errorMode is 'collect')
   */
  getErrors(): ErrorRecord[];

  /**
   * Clear the document content
   */
  clear(): Promise<DocFlow>;
}

// ============================================================================
// QUERY RESULT CLASS
// ============================================================================

declare class QueryResult {
  /** The DocFlow instance */
  readonly docflow: DocFlow;
  /** Found nodes */
  readonly nodes: NodeWithPath[];
  /** Selector used */
  readonly selector: Selector;
  /** Number of nodes found */
  readonly count: number;

  constructor(docflow: DocFlow, nodes: NodeWithPath[], selector: Selector);

  /**
   * Get first matching node
   */
  first(): NodeWithPath | null;

  /**
   * Get last matching node
   */
  last(): NodeWithPath | null;

  /**
   * Map over results
   */
  map<T>(fn: (node: NodeWithPath, index: number) => T): T[];

  /**
   * Filter results
   */
  filter(fn: (node: NodeWithPath, index: number) => boolean): QueryResult;

  /**
   * Get text content of all nodes
   */
  text(): string;

  /**
   * Get text from each node separately
   */
  texts(): string[];

  /**
   * Get array of nodes
   */
  toArray(): NodeWithPath[];

  /**
   * Transform all found nodes
   */
  transform(transformer: TransformFunction): Promise<DocFlow>;
}

// ============================================================================
// BATCH PROCESSOR CLASS
// ============================================================================

declare class BatchProcessor {
  constructor(options?: BatchProcessorConfig);

  /**
   * Process multiple documents
   */
  process(files: string[], pipeline: PipelineFunction): Promise<BatchSummary>;
}

// ============================================================================
// QUERY ENGINE CLASS
// ============================================================================

declare class QueryEngine {
  constructor(json: ProseMirrorJSON);

  /**
   * Find nodes matching selector
   */
  find(selector: Selector): NodeWithPath[];
}

// ============================================================================
// TRANSFORMATION HELPERS
// ============================================================================

declare namespace Transforms {
  /**
   * Convert text to title case
   */
  export function toTitleCase(text: string): string;

  /**
   * Convert text to sentence case
   */
  export function toSentenceCase(text: string): string;

  /**
   * Convert text to uppercase
   */
  export function toUpperCase(text: string): string;

  /**
   * Convert text to lowercase
   */
  export function toLowerCase(text: string): string;

  /**
   * Create a replace transform
   */
  export function replace(pattern: string | RegExp, replacement: string): TransformFunction;

  /**
   * Create an add prefix transform
   */
  export function addPrefix(prefix: string): TransformFunction;

  /**
   * Create an add suffix transform
   */
  export function addSuffix(suffix: string): TransformFunction;

  /**
   * Create a trim whitespace transform
   */
  export function trim(): TransformFunction;

  /**
   * Create a set attributes transform
   */
  export function setAttrs(attrs: Record<string, any>): TransformFunction;

  /**
   * Create a remove attribute transform
   */
  export function removeAttr(attrName: string): TransformFunction;

  /**
   * Create a remove transform
   */
  export function remove(condition: PredicateFunction): TransformFunction;
}

export { BatchProcessor, type BatchProcessorConfig, type BatchResult, type BatchSummary, DocFlow, type DocFlowConfig, type DocumentInfo, type DocumentTransformFunction, type ErrorRecord, type ExportFormat, type ExportOptions, type Mark, type NodeWithPath, type Operation, type PipelineFunction, type PredicateFunction, type ProseMirrorJSON, QueryEngine, QueryResult, type Selector, type TransformFunction, Transforms, type ValidationResult, DocFlow as default };