/**
 * xPDF - Fastify Plugin for PDF Generation and Manipulation
 * TypeScript Type Definitions
 *
 * @module @xenterprises/fastify-xpdf
 */

import { FastifyPluginAsync } from "fastify";

/** PDF generation options shared across generation methods */
export interface PDFGenerationOptions {
  /** Output filename (auto-generated if not provided) */
  filename?: string;
  /** Page format */
  format?: "A4" | "Letter" | "A3" | "A5" | "A6" | "Tabloid" | "Ledger" | "Legal" | "A0" | "A1" | "A2";
  /** Landscape orientation */
  landscape?: boolean;
  /** Page margins (CSS units: cm, mm, in, px) */
  margin?: { top?: string; right?: string; bottom?: string; left?: string } | string;
  /** Print background graphics and colors */
  printBackground?: boolean;
  /** Save to xStorage after generation */
  saveToStorage?: boolean;
  /** Storage folder path */
  folder?: string;
  /** Display header and footer */
  displayHeaderFooter?: boolean;
  /** Header HTML template (requires displayHeaderFooter: true) */
  headerTemplate?: string;
  /** Footer HTML template (requires displayHeaderFooter: true) */
  footerTemplate?: string;
}

/** Options for generateFromUrl */
export interface PDFFromUrlOptions extends PDFGenerationOptions {
  /** Puppeteer waitUntil value (default: "networkidle2") */
  waitFor?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
  /** Navigation timeout in ms (default: 30000) */
  timeout?: number;
}

/** PDF generation result */
export interface PDFGenerationResult {
  /** PDF buffer */
  buffer: Buffer;
  /** Generated filename */
  filename: string;
  /** File size in bytes */
  size: number;
  /** Storage key (only if saved to storage) */
  storageKey?: string;
  /** Public URL (only if saved to storage) */
  url?: string;
}

/** PDF merge result includes page count */
export interface PDFMergeResult extends PDFGenerationResult {
  /** Total page count in merged PDF */
  pageCount: number;
}

/** PDF form field descriptor */
export interface PDFFormField {
  /** Field name */
  name: string;
  /** Field type: text, checkbox, radio, dropdown, option, button, signature, unknown */
  type: string;
  /** Current field value */
  value: any;
}

/** PDF form filling options */
export interface PDFFormFillingOptions {
  /** Flatten form after filling (make non-editable, default: true) */
  flatten?: boolean;
  /** Output filename */
  filename?: string;
  /** Save to xStorage */
  saveToStorage?: boolean;
  /** Storage folder path */
  folder?: string;
}

/** PDF metadata */
export interface PDFMetadata {
  /** Number of pages */
  pageCount: number;
  /** Document title */
  title: string | null;
  /** Document author */
  author: string | null;
  /** Document subject */
  subject: string | null;
  /** Creator application */
  creator: string | null;
  /** Creation date */
  creationDate: Date | null;
  /** Last modification date */
  modificationDate: Date | null;
  /** File size in bytes */
  size: number;
}

/** Plugin configuration options */
export interface XPDFPluginOptions {
  /** Run Puppeteer in headless mode (default: true) */
  headless?: boolean;
  /** Chrome/Chromium launch arguments (default: ["--no-sandbox", "--disable-setuid-sandbox"]) */
  args?: string[];
  /** Enable saving to xStorage automatically (default: false) */
  useStorage?: boolean;
  /** Default storage folder (default: "pdfs") */
  defaultFolder?: string;
  /** Default page format (default: "A4") */
  format?: string;
  /** Print background by default (default: true) */
  printBackground?: boolean;
  /** Default page margins */
  margin?: { top?: string; right?: string; bottom?: string; left?: string };
}

/** Helper functions exported from the helpers subpath */
export namespace helpers {
  function generatePdfFilename(baseName?: string): string;
  function isValidPdfBuffer(buffer: any): boolean;
  function getPdfMetadata(buffer: Buffer): { size: number };
  function formatPdfOptions(options: any, defaults: any): any;
  function sanitizeFilename(filename: string): string;
  function wrapHtmlTemplate(content: string): string;
  function parseMargin(margin: any): { top?: string; right?: string; bottom?: string; left?: string };
  function getPageFormat(format?: string): { width: number; height: number };
  function saveToStorage(fastify: any, buffer: Buffer, filename: string, folder: string): Promise<{ storageKey: string; url: string } | null>;
}

/** xPDF service methods available on fastify.xPDF */
export interface XPDFService {
  /** Generate PDF from HTML content */
  generateFromHtml(html: string, options?: PDFGenerationOptions): Promise<PDFGenerationResult>;
  /** Generate PDF from Markdown content */
  generateFromMarkdown(markdown: string, options?: PDFGenerationOptions): Promise<PDFGenerationResult>;
  /** Generate PDF by navigating to a URL */
  generateFromUrl(url: string, options?: PDFFromUrlOptions): Promise<PDFGenerationResult>;
  /** Fill PDF form fields */
  fillForm(pdfBuffer: Buffer, fieldValues: Record<string, any>, options?: PDFFormFillingOptions): Promise<PDFGenerationResult>;
  /** List all form fields in a PDF */
  listFormFields(pdfBuffer: Buffer): Promise<PDFFormField[]>;
  /** Merge multiple PDFs into one */
  mergePDFs(pdfBuffers: Buffer[], options?: { filename?: string; saveToStorage?: boolean; folder?: string }): Promise<PDFMergeResult>;
  /** Extract specific pages from a PDF (zero-based indices) */
  extractPages(pdfBuffer: Buffer, pageIndices: number[], options?: { filename?: string; saveToStorage?: boolean; folder?: string }): Promise<PDFMergeResult>;
  /** Get number of pages in a PDF */
  getPageCount(pdfBuffer: Buffer): Promise<number>;
  /** Get PDF metadata (page count, title, author, dates, size) */
  getMetadata(pdfBuffer: Buffer): Promise<PDFMetadata>;
}

declare module "fastify" {
  interface FastifyInstance {
    xPDF: XPDFService;
  }
}

declare const xPDF: FastifyPluginAsync<XPDFPluginOptions>;
export default xPDF;
export { xPDF };