@mirawision/copily/core.d.ts

A comprehensive clipboard manipulation library for TypeScript, providing functionalities for copying/pasting text, HTML, JSON, images, files, and smart content detection.

/**
 * Copy plain text to the system clipboard.
 *
 * Requires a secure context and Clipboard API support.
 *
 * @param text Plain text to copy.
 * @returns Resolves when the text is written to the clipboard.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 * @throws {ClipboardPermissionError} If the write operation is denied or fails.
 * @example
 * await copyText('Hello world');
 */
declare function copyText(text: string): Promise<void>;
/**
 * Read plain text from the system clipboard.
 *
 * @returns Resolves to the clipboard text. Returns an empty string if the
 *          clipboard is empty or cannot be read.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 * @example
 * const text = await pasteText();
 */
declare function pasteText(): Promise<string>;
/**
 * Copy HTML content to the clipboard with a plain-text fallback.
 *
 * The HTML is sanitized before being written. A text/plain version (tags
 * stripped) is also provided for consumers that only support plain text.
 *
 * @param html HTML string to copy.
 * @returns Resolves when the HTML is written to the clipboard.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 * @throws {ClipboardPermissionError} If the write operation fails.
 * @example
 * await copyHTML('<strong>Hello</strong>');
 */
declare function copyHTML(html: string): Promise<void>;
/**
 * Read HTML content from the clipboard.
 *
 * Attempts to read 'text/html' first, falling back to plain text via
 * {@link pasteText} when HTML is not present.
 *
 * @returns Resolves to the HTML string (or plain text). Returns an empty
 *          string on failure.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 */
declare function pasteHTML(): Promise<string>;
/**
 * Copy a JSON-serializable object to the clipboard as formatted text.
 *
 * @param obj Object to stringify and copy.
 * @returns Resolves when the JSON string is written to the clipboard.
 * @example
 * await copyJSON({ id: 1 });
 */
declare function copyJSON(obj: object): Promise<void>;
/**
 * Parse the clipboard content as JSON.
 *
 * @returns Resolves to the parsed object.
 * @throws {ClipboardFormatError} If the clipboard content is not valid JSON
 *         or cannot be parsed.
 * @example
 * const data = await pasteJSON();
 */
declare function pasteJSON(): Promise<object>;
/**
 * Copy an image to the clipboard.
 *
 * Accepts a Blob, an HTMLImageElement, or a URL string which will be fetched
 * and converted to a Blob.
 *
 * @param image Image Blob, HTMLImageElement, or URL string.
 * @returns Resolves when the image is written to the clipboard.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 * @throws {ClipboardPermissionError} If the write operation fails.
 */
declare function copyImage(image: Blob | HTMLImageElement | string): Promise<void>;
/**
 * Read an image from the clipboard.
 *
 * @returns Resolves to an image Blob, or null if no image is present.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 */
declare function pasteImage(): Promise<Blob | null>;
/**
 * Copy a file to the clipboard.
 *
 * @param file File or Blob to copy.
 * @returns Resolves when the file is written to the clipboard.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 * @throws {ClipboardPermissionError} If the write operation fails.
 */
declare function copyFile(file: File | Blob): Promise<void>;
/**
 * Read a non-image file from the clipboard.
 *
 * The first non-image item is returned as a File, or null if not found.
 *
 * @returns Resolves to a File instance or null if none is present.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 */
declare function pasteFile(): Promise<File | null>;
/**
 * Clear clipboard content by writing an empty text payload.
 *
 * @returns Resolves when the clipboard has been cleared.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 * @throws {ClipboardPermissionError} If the write operation fails.
 */
declare function clearClipboard(): Promise<void>;
/**
 * Legacy fallback to copy text using `document.execCommand('copy')`.
 *
 * This is synchronous and intended as a last-resort for environments without
 * Clipboard API support.
 *
 * @param text Plain text to copy.
 * @example
 * fallbackCopyText('hello');
 */
declare function fallbackCopyText(text: string): void;
export { copyText, pasteText, copyHTML, pasteHTML, copyJSON, pasteJSON, copyImage, pasteImage, copyFile, pasteFile, clearClipboard, fallbackCopyText };