@mirawision/copily/utils.d.ts

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

/**
 * Check if the Clipboard API is supported in the current environment.
 *
 * @returns True if `navigator.clipboard` is available.
 */
declare function supportsClipboardAPI(): boolean;
/**
 * Check if the clipboard supports a specific MIME format.
 *
 * Note: The Clipboard API does not expose a formal capability query for
 * formats. This function validates against a curated list of common types.
 *
 * @param format MIME type (e.g. `text/html`).
 * @returns True when the format is recognized.
 */
declare function supportsFormat(format: string): boolean;
/**
 * Get available MIME formats currently present on the clipboard.
 *
 * @returns Resolves to an array of MIME types; returns an empty array when
 *          formats cannot be read.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 */
declare function getClipboardFormats(): Promise<string[]>;
/**
 * Validate and sanitize an HTML string.
 *
 * Removes script/iframe tags and common inline event handlers. For strict
 * sanitization in production, consider a dedicated sanitizer like DOMPurify.
 *
 * @param html HTML string.
 * @returns Sanitized HTML string.
 */
declare function sanitizeHTML(html: string): string;
/**
 * Detect if a string is a URL.
 *
 * Accepts http(s), ftp, mailto and tel protocols.
 *
 * @param text String to test.
 * @returns True when the input is a URL.
 */
declare function isURL(text: string): boolean;
/**
 * Detect if a string is an email address.
 *
 * @param text String to test.
 * @returns True when the input matches a simple email regex.
 */
declare function isEmail(text: string): boolean;
/**
 * Detect if a string looks like a One-Time Passcode (OTP).
 *
 * Matches 4-8 digit codes or 6-character alphanumerics.
 *
 * @param text String to test.
 * @returns True when the input matches OTP patterns.
 */
declare function isOTP(text: string): boolean;
/**
 * Detect if a string is valid JSON.
 *
 * @param text String to test.
 * @returns True when `JSON.parse` succeeds.
 */
declare function isJSON(text: string): boolean;
/**
 * Convert an image to a Blob.
 *
 * For a URL string, the image is fetched. For an `HTMLImageElement`, a canvas
 * conversion is performed.
 *
 * @param image URL string or `HTMLImageElement`.
 * @returns Resolves to a Blob of the image data.
 */
declare function imageToBlob(image: HTMLImageElement | string): Promise<Blob>;
/**
 * Create a hidden textarea for legacy copy operations.
 *
 * @returns The created textarea element.
 */
declare function createTemporaryElement(): HTMLTextAreaElement;
/**
 * Remove a temporary element from the DOM.
 *
 * @param element The element to remove.
 */
declare function removeTemporaryElement(element: HTMLTextAreaElement): void;
/**
 * Check if the current page context is secure (HTTPS or otherwise).
 *
 * @returns True when in a secure context.
 */
declare function isSecureContext(): boolean;
/**
 * Request clipboard permission by attempting a read.
 *
 * @returns Resolves true on success.
 * @throws {ClipboardUnsupportedError} If the Clipboard API is unavailable.
 * @throws {ClipboardPermissionError} If the operation is not permitted.
 */
declare function requestClipboardPermission(): Promise<boolean>;
export { supportsClipboardAPI, supportsFormat, getClipboardFormats, sanitizeHTML, isURL, isEmail, isOTP, isJSON, imageToBlob, createTemporaryElement, removeTemporaryElement, isSecureContext, requestClipboardPermission };