@mirawision/chrome-api
Version:
A comprehensive TypeScript library for Chrome Extension API, providing type-safe wrappers and utilities for bookmarks, commands, context menus, cookies, downloads, storage, notifications, runtime, scripting, and side panel functionalities.
168 lines (167 loc) • 6.73 kB
TypeScript
/// <reference types="chrome" />
interface DownloadOptions {
url: string;
filename?: string;
conflictAction?: chrome.downloads.FilenameConflictAction;
saveAs?: boolean;
method?: 'GET' | 'POST';
headers?: chrome.downloads.HeaderNameValuePair[];
body?: string;
}
interface DownloadQuery {
query?: string[];
startedBefore?: string;
startedAfter?: string;
endedBefore?: string;
endedAfter?: string;
totalBytesGreater?: number;
totalBytesLess?: number;
filenameRegex?: string;
urlRegex?: string;
limit?: number;
orderBy?: string[];
id?: number;
url?: string;
filename?: string;
danger?: chrome.downloads.DangerType;
mime?: string;
startTime?: string;
endTime?: string;
state?: 'in_progress' | 'interrupted' | 'complete';
paused?: boolean;
error?: number;
bytesReceived?: number;
totalBytes?: number;
fileSize?: number;
exists?: boolean;
}
/**
* A class that provides a type-safe wrapper around Chrome's downloads API.
* This class allows you to download files, manage downloads, and monitor download progress.
* It provides functionality for starting, pausing, resuming, and canceling downloads,
* as well as managing download history and file system interactions.
*/
declare class Downloads {
/**
* Initiates a download.
* @param options - The download options including URL and optional filename
* @returns A promise that resolves to the download ID
* @throws {Error} If there's an error starting the download
*/
static download(options: DownloadOptions): Promise<number>;
/**
* Searches for downloads matching the given criteria.
* @param query - The search criteria
* @returns A promise that resolves to an array of matching download items
* @throws {Error} If there's an error performing the search
*/
static search(query: DownloadQuery): Promise<chrome.downloads.DownloadItem[]>;
/**
* Pauses a download.
* @param downloadId - The ID of the download to pause
* @returns A promise that resolves when the download is paused
* @throws {Error} If there's an error pausing the download
*/
static pause(downloadId: number): Promise<void>;
/**
* Resumes a paused download.
* @param downloadId - The ID of the download to resume
* @returns A promise that resolves when the download is resumed
* @throws {Error} If there's an error resuming the download
*/
static resume(downloadId: number): Promise<void>;
/**
* Cancels a download.
* @param downloadId - The ID of the download to cancel
* @returns A promise that resolves when the download is cancelled
* @throws {Error} If there's an error cancelling the download
*/
static cancel(downloadId: number): Promise<void>;
/**
* Retrieves the icon for a downloaded file.
* @param downloadId - The ID of the download
* @param options - Optional settings for the icon (size: 16 or 32 pixels)
* @returns A promise that resolves to the icon URL
* @throws {Error} If there's an error retrieving the icon or if no icon is available
*/
static getFileIcon(downloadId: number, options?: {
size?: 16 | 32;
}): Promise<string>;
/**
* Opens a downloaded file.
* @param downloadId - The ID of the download to open
* @returns A promise that resolves when the file is opened
* @throws {Error} If there's an error opening the file
*/
static open(downloadId: number): Promise<void>;
/**
* Shows a downloaded file in its folder.
* @param downloadId - The ID of the download to show
* @returns A promise that resolves when the file is shown
*/
static show(downloadId: number): Promise<void>;
/**
* Shows the default downloads folder.
* @returns A promise that resolves when the folder is shown
*/
static showDefaultFolder(): Promise<void>;
/**
* Erases matching downloads from history.
* @param query - The criteria for downloads to erase
* @returns A promise that resolves to an array of erased download IDs
* @throws {Error} If there's an error erasing the downloads
*/
static erase(query: DownloadQuery): Promise<number[]>;
/**
* Removes a downloaded file from disk.
* @param downloadId - The ID of the download to remove
* @returns A promise that resolves when the file is removed
* @throws {Error} If there's an error removing the file
*/
static removeFile(downloadId: number): Promise<void>;
/**
* Adds a listener for download creation events.
* @param callback - Function called when a new download is created
*/
static addCreatedListener(callback: (downloadItem: chrome.downloads.DownloadItem) => void): void;
/**
* Adds a listener for download erasure events.
* @param callback - Function called when a download is erased from history
*/
static addErasedListener(callback: (downloadId: number) => void): void;
/**
* Adds a listener for download state change events.
* @param callback - Function called when a download's state changes
*/
static addChangedListener(callback: (downloadDelta: chrome.downloads.DownloadDelta) => void): void;
/**
* Adds a listener for filename determination events.
* @param callback - Function called when a download's filename is being determined
*/
static addDeterminingFilenameListener(callback: (downloadItem: chrome.downloads.DownloadItem, suggest: (suggestion?: {
filename: string;
}) => void) => void): void;
/**
* Removes a listener for download creation events.
* @param callback - The listener function to remove
*/
static removeCreatedListener(callback: (downloadItem: chrome.downloads.DownloadItem) => void): void;
/**
* Removes a listener for download erasure events.
* @param callback - The listener function to remove
*/
static removeErasedListener(callback: (downloadId: number) => void): void;
/**
* Removes a listener for download state change events.
* @param callback - The listener function to remove
*/
static removeChangedListener(callback: (downloadDelta: chrome.downloads.DownloadDelta) => void): void;
/**
* Removes a listener for filename determination events.
* @param callback - The listener function to remove
*/
static removeDeterminingFilenameListener(callback: (downloadItem: chrome.downloads.DownloadItem, suggest: (suggestion?: {
filename: string;
}) => void) => void): void;
}
export { Downloads, DownloadOptions, DownloadQuery };