import type { Page, Locator } from "playwright-core";
import type { ReadStream } from "fs";

/**
 * Represents a PDF file and provides methods to interact with it.
 *
 * @class
 *
 * @example
 * ```typescript PdfFile
 * import { PdfFile } from "@intuned/sdk/files"
 *
 * const pdf = new PdfFile(pdfBuffer);
 *
 * ```
 */
export declare class PdfFile {
  /**
   * Creates an instance of PdfFile.
   *
   * @param {Buffer} data - The binary data of the PDF file.
   */
  constructor(data: Buffer);

  /**
   * Creates a PdfFile instance from a URL.
   *
   * @param {string} url - The URL of the PDF file.
   * @returns {Promise<PdfFile>} A promise that resolves to a PdfFile instance.
   *
   * @example
   * ```typescript fromUrl
   * import { PdfFile } from "@intuned/sdk/files"
   *
   * const pdf = await PdfFile.fromUrl('https://example.com/file.pdf');
   *
   * ```
   */
  static fromUrl(url: string): Promise<PdfFile>;

  /**
   * Searches for a string within the PDF file.
   *
   * @param {string} search - The string to search for.
   * @param {SearchPdfConfigs} [options] - Optional. Search configuration options.
   * @returns {Promise<SearchPdfResult[]>} A promise that resolves to an array of search results.
   *
   * @example
   * ```typescript Without options
   * import { PdfFile } from "@intuned/sdk/files"
   *
   * const pdf = await PdfFile.fromUrl('https://example.com/file.pdf');
   * const results = await pdf.search('keyword');
   *
   * console.log(results);
   * ```
   *
   * @example
   * ```typescript With options
   * import { PdfFile } from "@intuned/sdk/files"
   *
   * const pdf = await PdfFile.fromUrl('https://example.com/file.pdf');
   * const results = await pdf.search('keyword', { matchCase: true });
   *
   * console.log(results);
   * ```
   */
  search(
    search: string,
    options?: SearchPdfConfigs
  ): Promise<SearchPdfResult[]>;

  /**
   * Gets the text content of specified pages in the PDF file. Does not support links.
   *
   * @param {number[]} [pageNumbers] - Optional. An array of page numbers to get content from.
   * @returns {Promise<PdfFileContentItem[]>} A promise that resolves to the content of the specified pages.
   *
   * @example
   * ```typescript getContent
   * import { PdfFile } from "@intuned/sdk/files"
   *
   * const pdf = await PdfFile.fromUrl('https://example.com/file.pdf');
   * const content = await pdf.getContent([1, 2, 3]);
   * console.log(content);
   * ```
   */
  getContent(pageNumbers?: number[]): Promise<PdfFileContentItem[]>;

  /**
   * Gets the total number of pages in the PDF file.
   *
   * @returns {Promise<number>} A promise that resolves to the number of pages.
   *
   * @example
   * ```typescript pagesCount
   * import { PdfFile } from "@intuned/sdk/files"
   *
   * const pdf = await PdfFile.fromUrl('https://example.com/file.pdf');
   * const pageCount = await pdf.pagesCount();
   * console.log(pageCount);
   * ```
   */
  pagesCount(): Promise<number>;
}

/**
 * Configuration options for searching within a PDF file.
 *
 * @interface
 * @property {number} [contextWindow] - Optional. Number of context letters around the search term to return.
 * @property {boolean} [matchCase] - Optional. Whether to match case during the search.
 * @property {boolean} [wholeWord] - Optional. Whether to match whole words only.
 */
export interface SearchPdfConfigs {
  contextWindow?: number;
  matchCase?: boolean;
  wholeWord?: boolean;
}

/**
 * Represents a search result within a PDF file.
 *
 * @interface
 * @property {string} context - The context around the search term.
 * @property {number} page - The page number where the search term was found.
 */
export interface SearchPdfResult {
  context: string;
  page: number;
}

/**
 * Represents the content of a PDF file.
 *
 * @interface
 * @property {number} pageNumber - The page number of the content.
 * @property {string} content - The content of the page.
 */
export interface PdfFileContentItem {
  pageNumber: number;
  content: string;
}

/**
 * Represents the content of a sheet in an Excel file.
 *
 * @interface
 * @property {string | undefined} name - The name of the sheet.
 * @property {(string | number | Date | undefined)[][]} content - The content of the sheet.
 */
export interface ExcelFileSheet {
  name: string | undefined;
  content: (string | number | Date | undefined)[][];
}

/**
 * Represents an Excel file and provides methods to interact with it.
 *
 * @class
 *
 * @example
 * ```typescript ExcelFile
 * import { ExcelFile }from "@intuned/sdk/files"
 *
 * const excelFile = new ExcelFile(excelBuffer);
 * ...
 * ```
 */
export declare class ExcelFile {
  /**
   * Creates an instance of ExcelFile.
   *
   * @param {Buffer} data - The binary data of the Excel file.
   */
  constructor(data: Buffer);

  /**
   * Creates an ExcelFile instance from a URL.
   *
   * @param {string} url - The URL of the Excel file.
   * @returns {Promise<ExcelFile>} A promise that resolves to an ExcelFile instance.
   *
   * @example
   * ```typescript fromUrl
   * import { ExcelFile }from "@intuned/sdk/files"
   *
   * const excel = await ExcelFile.fromUrl('https://example.com/file.xlsx');
   * console.log(excel);
   * ```
   */
  static fromUrl(url: string): Promise<ExcelFile>;

  /**
   * Gets the content of specified sheets in the Excel file.
   *
   * @param {string[]} [sheetNames] - Optional. An array of sheet names to get content from.
   * @returns {Promise<ExcelFileSheet[]>} A promise that resolves to the content of the specified sheets.
   *
   * @example
   * ```typescript getContent
   * import { ExcelFile }from "@intuned/sdk/files"
   *
   * const content = await excel.getContent(['Sheet1', 'Sheet2']);
   * console.log(content);
   * ```
   */
  getContent(sheetNames?: string[]): Promise<ExcelFileSheet[]>;
}

/**
 * Represents an s3 file, and provides some functions to operate over it
 *
 * @interface
 */
export declare interface File {
  /**
   * Gets S3 URL descriptor of the file.
   *
   * @throws {Error} Throws an error if the endpoint option is provided in the uploadFileToS3 method options.
   * @returns {string} The URL descriptor of the file.
   */
  urlDescriptor(): string;

  /**
   * Gets file path in the s3 bucket
   *
   * @returns {string} The file path in the s3 bucket.
   */
  filePath(): string;

  /**
   * Generates a signed URL for the file.
   *
   * @param {Object} [options] - Optional. Options for generating the signed URL.
   * @param {number | string} [options.expiresIn] - The expiration time for the signed URL in seconds.
   * @returns {Promise<string>} A promise that resolves to the signed URL.
   *
   * @example
   * ```typescript generateSignedUrl
   * import { File } from "@intuned/sdk/files";
   *
   * const signedUrl = await file.generateSignedUrl({ expiresIn: 1000 });
   * console.log(signedUrl);
   * ```
   */
  generateSignedUrl(options?: { expiresIn: number }): Promise<string>;
}

/**
 * Downloads a file from a URL.
 *
 * @param {Page} page - The Playwright Page object.
 * @param {DownloadFileAutoStrategy} strategy - The strategy to use for downloading the file. URL auto strategy.
 * @param {string} strategy.url - The URL of the file to download.
 * @returns {Promise<Download>} A promise that resolves to a Download object.
 *
 * @example
 * ```typescript
 * import { downloadFile } from "@intuned/sdk/files";
 *
 * const download = await downloadFile(page, { url: "https://example.com/file.pdf" });
 * console.log(await download.path());
 * ```
 */
export declare function downloadFile(
  page: Page,
  strategy: { url: string; type?: "Auto" }
): Promise<Download>;

/**
 * Downloads a file by clicking the specified locator.
 *
 * @param {Page} page - The Playwright Page object.
 * @param {DownloadFileAutoStrategy} strategy - The strategy to use for downloading the file. Locator auto strategy.
 * @param {Locator} strategy.locator - The locator of the element to click to download the file.
 * @param {number} [options.clickTimeout] - Optional. The maximum time in milliseconds to wait for the element to be clickable. Defaults to Playwright's default timeout.
 * @returns {Promise<Download>} A promise that resolves to a Download object.
 *
 * @example
 * ```typescript
 * import { downloadFile } from "@intuned/sdk/files";
 *
 * const download = await downloadFile(page, { locator: page.locator(".download_button") });
 * console.log(await download.path());
 * ```
 */
export declare function downloadFile(
  page: Page,
  strategy: { locator: Locator; type?: "Auto" }
): Promise<Download>;

/**
 * Downloads a file using the specified trigger function.
 *
 * @param {Page} page - The Playwright Page object.
 * @param {DownloadFileAutoStrategy} strategy - The strategy to use for downloading the file. Trigger auto strategy.
 * @param {(page: Page) => Promise<void>} strategy.trigger - The function to trigger the download.
 * @returns {Promise<Download>} A promise that resolves to a Download object.
 *
 * @example
 * ```typescript
 * import { downloadFile } from "@intuned/sdk/files";
 *
 * const download = await downloadFile(page, {
 *   trigger: async (page) => {
 *     await page.locator(".download_button").click();
 *   }
 * });
 *
 * console.log(await download.path());
 * ```
 */
export declare function downloadFile(
  page: Page,
  strategy: { trigger: (page: Page) => Promise<void>; type?: "Auto" }
): Promise<Download>;

/**
 *
 * Downloads the current page as a PDF file.
 *
 * @param {Page} page - The Playwright Page object.
 * @param {DownloadPageAsPdfStrategy} strategy - PrintPageAsPdf strategy to download the page as pdf.
 *
 * @example
 * ```typescript PrintPageAsPdf
 * import { downloadFile } from "@intuned/sdk/files";
 *
 * await page.goto("https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html")
 *
 * // use PrintPageAsPdf strategy when you download a pdf version of the open webpage.
 * const downloadedFile = await downloadFile(page, {
 *   type: "PrintPageAsPdf",
 * })
 *
 * console.log(await downloadedFile.path());
 * ```
 */
export declare function downloadFile(
  page: Page,
  strategy: {
    type: "PrintPageAsPdf";
    options?: Parameters<Page["pdf"]>[0];
  }
): Promise<Download>;

/**
 * @deprecated Use `downloadFile` function with `DownloadFileAutoStrategy` instead.
 *
 * Downloads a file using the specified manual strategy.
 *
 * @param {Page} page - The Playwright Page object.
 * @param {DownloadFileManualStrategy} strategy - The manual strategy to use for downloading the file.
 * @returns {Promise<Download>} A promise that resolves to a Download object.
 *
 * @example
 * ```typescript DirectLink
 * import { downloadFile } from "@intuned/sdk/files";
 *
 * // use DirectLink strategy when you have the url of the pdf.
 * const download = await downloadFile(page, { type:"DirectLink", link:"https://www.gemini.com/documents/credit/Test_PDF.pdf" });
 * console.log(await download.path()); // Outputs the file path
 * ```
 * @example
 * ```typescript DownloadByOpeningNewTab
 * import { downloadFile } from "@intuned/sdk/files";
 *
 * await page.goto("https://sandbox.intuned.dev/pdfs")
 *
 * // use DownloadByOpeningNewTab strategy when you have to click on a button to open the pdf in a new tab in the browser viewer.
 * const downloadedFile = await downloadFile(page, {
 *   type: "DownloadByOpeningNewTab",
 *   downloadTrigger: (page) => page.locator("table > tbody > tr:nth-child(1) > td:nth-child(4) > a").click()
 * })
 *
 * console.log(await download.path()); // Outputs the file path
 * ```
 *
 * @example
 * ```typescript DownloadFromDirectLink
 * import { downloadFile } from "@intuned/sdk/files";
 *
 * await page.goto("https://freetestdata.com/document-files/pdf/")
 *
 * // use DownloadFromDirectLink strategy when the file gets downloaded immediately after you trigger an action on the page.
 * const downloadedFile = await downloadFile(page, {
 *   type: "DownloadFromDirectLink",
 *   downloadTrigger: page.locator('.elementor-button').first()
 * })
 *
 * console.log(await downloadedFile.path());
 * ```
 *
 * @example
 * ```typescript NavigateAndDownloadFromThirdPartyFileViewer
 *  import { downloadFile } from "@intuned/sdk/files";
 *
 *  // use NavigateAndDownloadFromThirdPartyFileViewer strategy when the file is viewed in a custom(non standard) viewer.
 *  const downloadedFile = await downloadFile(page, {
 *    type: "NavigateAndDownloadFromThirdPartyFileViewer",
 *    linkToGoTo: "https://txdir.widen.net/view/pdf/ki9p5mluhv/DIR-CPO-4582-RFO-DIR-CPO-TMP-445.pdf?t.download=true&u=tmwul0",
 *    downloadActionOnFileViewerPage: (page) => page.locator("#download").click()
 *  })
 *
 *  console.log(await downloadedFile.path());
 *```
 */
export declare function downloadFile(
  page: Page,
  strategy: DownloadFileManualStrategy
): Promise<Download>;

/**
 * Represents a downloaded file.
 *
 * @interface
 * @property {Function} delete - Deletes the downloaded file.
 * @property {Function} path - Gets the path of the downloaded file.
 * @property {Function} suggestedFilename - Returns suggested filename for this download. It is typically computed by the browser from the `Content-Disposition` response header or the download attribute. See the spec on [whatwg](https://html.spec.whatwg.org/#downloading-resources). Different browsers can use different logic for computing it. when the file is downloaded using  `DirectLink` or `PrintPageAsPdf` this will always return undefined,
 */
export interface Download {
  delete: () => Promise<void>;
  path: () => Promise<null | string>;
  suggestedFilename: () => string | undefined;
  mimeType: () => Promise<string | undefined>;
}

/**
 * The strategy to use for downloading a file.
 * Auto strategy automatically downloads the file depending on its input.
 * Manual strategy requires providing the specific strategy to use for downloading the file.
 */
export type DownloadFileStrategy =
  | DownloadFileAutoStrategy
  | DownloadFileManualStrategy
  | DownloadPageAsPdfStrategy;

/**
 * In auto strategy, the file is downloaded automatically depending on the input.
 * ## Inputs:
 * - `url`: The URL of the file to download.
 * - `locator`: The locator of the element to click to download the file.
 * - `trigger`: The function to trigger the browser download.
 */
export type DownloadFileAutoStrategy =
  | {
      type?: "Auto";
      url: string;
    }
  | {
      type?: "Auto";
      locator: Locator;
    }
  | {
      type?: "Auto";
      trigger: (page: Page) => Promise<void>;
    };

/**
 * ## Strategies:
 *
 * - `DownloadByOpeningNewTab`: use this strategy when the file you want to download get open in a new tab after doing some action on the page.
 * - `DownloadFromDirectLink`:  use this strategy when there's a button or action you do in the page, and the file gets downloaded automatically in the same tab.
 * - `NavigateAndDownloadFromThirdPartyFileViewer`: use this strategy when the file is viewed in a custom(non standard) viewer
 * - `DirectLink`: use this strategy when you have the file url.
 */
export type DownloadFileManualStrategy =
  | {
      // DownloadViaNewTab
      // ContentLink
      // button click
      // for pdf open new page and download
      // for other files download immediately
      type: "DownloadByOpeningNewTab";
      downloadTrigger: ((page: Page) => Promise<void>) | Locator;
    }
  | {
      // button click
      // download immediately for pdf and other files
      type: "DownloadFromDirectLink";
      downloadTrigger: ((page: Page) => Promise<void>) | Locator;
    }
  | {
      // link click
      // new page for all types of documents
      // new page is a 3rd party website
      // click on download for 3rd party website
      // ThirdPartyViewer
      type: "NavigateAndDownloadFromThirdPartyFileViewer";
      linkToGoTo: string;
      downloadActionOnFileViewerPage: (
        thirdPartyViewerPage: Page
      ) => Promise<void>;
    }
  | {
      type: "DirectLink";
      link: string;
    };

/**
 * use this action when you download a pdf version of the open webpage.
 */
export type DownloadPageAsPdfStrategy = {
  type: "PrintPageAsPdf";
  options?: Parameters<Page["pdf"]>[0];
};

/**
 * Configuration to connect to S3 bucket
 * @interface
 * @property {string} bucket - The S3 bucket name.
 * @property {string} region - The AWS region.
 * @property {string} accessKeyId - The AWS access key ID.
 * @property {string} secretAccessKey - The AWS secret access key.
 */
export interface S3Configs {
  bucket: string;
  region: string;
  accessKeyId: string;
  secretAccessKey: string;
}

export interface S3UploadOptions {
  fileNameOverride?: string;
  s3Configs?: S3Configs;
  endpoint?: string;
  contentType?: string;
}

export type S3UploadableFile =
  | Download
  | string
  | Uint8Array
  | Buffer
  | ReadStream;

/**
 * Uploads a file to S3 bucket.
 *
 * @param {Download | string | Uint8Array | Buffer | ReadStream} file - The file to upload, it can be a downloaded file by the downloadFile function or another content, the file can be  `Download | string | Uint8Array | Buffer | ReadStream`
 * @param {Object} options - The options for uploading the file.
 * @param {string} [options.fileNameOverride] - Optional. Override for the file name.
 * @param {S3Configs} [options.s3Configs] - Optional. S3 configuration options.
 * @param {string} [options.endpoint] - Optional. Custom S3 endpoint.
 * @param {string} [options.contentType] - Optional. The MIME type of the file, used to specify the type of content being uploaded to S3.
 * @returns {Promise<File>} A promise that resolves to a File object.
 *
 *
 * @example
 * ```typescript Download
 * import { downloadFile, PersistFileStrategy, uploadFileToS3 } from "@intuned/sdk/files";
 *
 * const download = await downloadFile(page, {
 *   type: "DownloadByOpeningNewTab",
 *   downloadTrigger: (page) => page.locator(".download_button").click(),
 * });
 *
 * const s3Configs: S3Configs = {
 *   bucket: 'my-bucket',
 *   region: 'us-west-1',
 *   accessKeyId: '....',
 *   secretAccessKey: '....'
 * };
 *
 * const uploadedFile = await uploadFileToS3(download, { s3Configs });
 * console.log(uploadedFile.urlDescriptor());
 * ```
 * @example
 * ```typescript ReadStream
 * import { uploadFileToS3, S3Configs } from "@intuned/sdk/files";
 * import { ReadStream } from "node:fs";
 *
 * const file: ReadStream = ...; // Assume ReadStream is initialized
 * const s3Configs: S3Configs = {
 *   bucket: 'my-bucket',
 *   region: 'us-west-1',
 *   accessKeyId: '....',
 *   secretAccessKey: '....'
 * };
 *
 * const uploadedFile = await uploadFileToS3(file, { s3Configs });
 * console.log(uploadedFile.urlDescriptor());
 * ```
 */

export declare function uploadFileToS3(
  file: S3UploadableFile,
  options?: S3UploadOptions
): Promise<File>;