@capgo/capacitor-printer 7.0.0

package/dist/esm/definitions.d.ts

@@ -0,0 +1,489 @@
+export interface PrinterPlugin {
+    /**
+     * Presents the printing UI to print files encoded as base64 strings.
+     *
+     * **Platform Behavior:**
+     * - **iOS**: Uses UIPrintInteractionController with base64 decoded data
+     * - **Android**: Uses PrintManager with base64 decoded data
+     * - **Web**: Creates a blob from base64 data and opens print dialog
+     *
+     * **Performance Warning:**
+     * Large files can lead to app crashes due to memory constraints when decoding base64.
+     * For files larger than 5MB, it's recommended to use printFile() instead.
+     *
+     * @param options - The base64 data and configuration for printing
+     * @returns Promise that resolves when print dialog is dismissed
+     * @throws Error if base64 data is invalid or printing fails
+     * @since 7.0.0
+     * @example
+     * ```typescript
+     * // Print a base64 encoded PDF
+     * await Printer.printBase64({
+     *   name: 'Invoice #12345',
+     *   data: 'JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...',
+     *   mimeType: 'application/pdf',
+     * });
+     *
+     * // Print a base64 encoded image
+     * await Printer.printBase64({
+     *   name: 'Product Photo',
+     *   data: '/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDA...',
+     *   mimeType: 'image/jpeg',
+     * });
+     * ```
+     */
+    printBase64(options: PrintBase64Options): Promise<void>;
+    /**
+     * Presents the printing UI to print device files.
+     *
+     * **Platform Behavior:**
+     * - **iOS**: Uses UIPrintInteractionController with file URL. Supports file:// paths or paths relative to app's documents directory.
+     * - **Android**: Uses PrintManager with file path. Supports both content:// URIs and file:// paths.
+     * - **Web**: Reads file and opens print dialog
+     *
+     * **Supported File Types:**
+     * - PDF documents (application/pdf)
+     * - Images: JPEG, PNG, GIF, HEIC, HEIF
+     *
+     * @param options - The file path and configuration for printing
+     * @returns Promise that resolves when print dialog is dismissed
+     * @throws Error if file path is invalid, file not found, or unsupported file type
+     * @since 7.0.0
+     * @example
+     * ```typescript
+     * // iOS: Print from app documents directory
+     * await Printer.printFile({
+     *   name: 'Contract',
+     *   path: 'file:///var/mobile/Containers/Data/Application/.../Documents/contract.pdf',
+     * });
+     *
+     * // Android: Print from content URI
+     * await Printer.printFile({
+     *   name: 'Receipt',
+     *   path: 'content://com.android.providers.downloads.documents/document/123',
+     *   mimeType: 'application/pdf',
+     * });
+     *
+     * // Android: Print from file path
+     * await Printer.printFile({
+     *   name: 'Photo',
+     *   path: 'file:///storage/emulated/0/Download/photo.jpg',
+     *   mimeType: 'image/jpeg',
+     * });
+     * ```
+     */
+    printFile(options: PrintFileOptions): Promise<void>;
+    /**
+     * Presents the printing UI to print HTML documents.
+     *
+     * **Platform Behavior:**
+     * - **iOS**: Renders HTML in WKWebView, then prints using UIPrintInteractionController
+     * - **Android**: Renders HTML in WebView, then prints using PrintManager
+     * - **Web**: Creates iframe with HTML content and triggers print dialog
+     *
+     * **HTML Requirements:**
+     * - Should be a complete HTML document with proper structure
+     * - Can include inline CSS styles or style tags
+     * - External resources (images, stylesheets) should use absolute URLs
+     * - Print-specific CSS can be added using @media print rules
+     *
+     * **CSS Print Styling:**
+     * Use CSS media queries to customize print output:
+     * - Control page breaks: page-break-before, page-break-after, page-break-inside
+     * - Hide elements: display: none for no-print classes
+     * - Adjust font sizes and colors for print
+     *
+     * @param options - The HTML content and configuration for printing
+     * @returns Promise that resolves when print dialog is dismissed
+     * @throws Error if HTML is invalid or printing fails
+     * @since 7.0.0
+     * @example
+     * ```typescript
+     * // Simple HTML document
+     * await Printer.printHtml({
+     *   name: 'Sales Report',
+     *   html: '<html><body><h1>Q4 Sales Report</h1><p>Revenue: $125,000</p></body></html>',
+     * });
+     *
+     * // HTML with print-specific CSS
+     * await Printer.printHtml({
+     *   name: 'Styled Invoice',
+     *   html: `
+     *     <html>
+     *       <head>
+     *         <style>
+     *           @media print {
+     *             body { font-size: 12pt; }
+     *             .no-print { display: none; }
+     *             h1 { page-break-before: always; }
+     *           }
+     *         </style>
+     *       </head>
+     *       <body>
+     *         <h1>Invoice #12345</h1>
+     *         <p>Amount due: $299.99</p>
+     *         <button class="no-print">Don't print this button</button>
+     *       </body>
+     *     </html>
+     *   `,
+     * });
+     * ```
+     */
+    printHtml(options: PrintHtmlOptions): Promise<void>;
+    /**
+     * Presents the printing UI to print PDF documents.
+     *
+     * **Platform Behavior:**
+     * - **iOS**: Uses UIPrintInteractionController with PDF file URL
+     * - **Android**: Uses PrintManager with PdfDocument
+     * - **Web**: Creates object URL and opens print dialog
+     *
+     * **File Path Requirements:**
+     * - **iOS**: Must be file:// path or relative to app's documents directory
+     * - **Android**: Supports content:// URIs (from downloads, media store) or file:// paths
+     * - **Web**: Must be accessible file path
+     *
+     * @param options - The PDF file path and configuration for printing
+     * @returns Promise that resolves when print dialog is dismissed
+     * @throws Error if PDF path is invalid, file not found, or not a valid PDF
+     * @since 7.0.0
+     * @example
+     * ```typescript
+     * // Print PDF from app storage
+     * await Printer.printPdf({
+     *   name: 'Annual Report 2024',
+     *   path: 'file:///var/mobile/Containers/Data/Application/.../Documents/report.pdf',
+     * });
+     *
+     * // Print PDF from Android downloads
+     * await Printer.printPdf({
+     *   name: 'Downloaded Document',
+     *   path: 'content://com.android.providers.downloads.documents/document/123',
+     * });
+     * ```
+     */
+    printPdf(options: PrintPdfOptions): Promise<void>;
+    /**
+     * Presents the printing UI to print web view content.
+     *
+     * Prints the current content displayed in your app's web view.
+     *
+     * **Platform Behavior:**
+     * - **iOS**: Uses UIPrintInteractionController with WKWebView's view printable
+     * - **Android**: Uses WebView.createPrintDocumentAdapter() with PrintManager
+     * - **Web**: Triggers window.print() for current page
+     *
+     * **Print Styling:**
+     * Supports CSS print media queries for customization. The web view's current
+     * styles will be applied, including any @media print rules.
+     *
+     * **Use Cases:**
+     * - Print the current app screen/page
+     * - Print web-based reports or dashboards
+     * - Print user-generated content displayed in web view
+     *
+     * @param options - Optional configuration for printing (name only)
+     * @returns Promise that resolves when print dialog is dismissed
+     * @throws Error if web view is not available or printing fails
+     * @since 7.0.0
+     * @example
+     * ```typescript
+     * // Print current web view with default name
+     * await Printer.printWebView();
+     *
+     * // Print with custom job name
+     * await Printer.printWebView({
+     *   name: 'Dashboard Screenshot',
+     * });
+     *
+     * // Use with print-specific CSS in your HTML
+     * // Add this to your app's CSS:
+     * // @media print {
+     * //   .no-print { display: none; }
+     * //   body { font-size: 12pt; }
+     * // }
+     * await Printer.printWebView({
+     *   name: 'User Profile',
+     * });
+     * ```
+     */
+    printWebView(options?: PrintOptions): Promise<void>;
+    /**
+     * Get the native Capacitor plugin version.
+     *
+     * Returns the hardcoded plugin version from native code (iOS/Android) or
+     * package version (Web). This is useful for debugging and ensuring plugin
+     * compatibility.
+     *
+     * @returns Promise that resolves with the plugin version string
+     * @throws Error if getting the version fails
+     * @since 7.0.0
+     * @example
+     * ```typescript
+     * const { version } = await Printer.getPluginVersion();
+     * console.log('Printer plugin version:', version);
+     * // Output: "7.0.0"
+     * ```
+     */
+    getPluginVersion(): Promise<{
+        version: string;
+    }>;
+}
+/**
+ * Options for printing base64 encoded data.
+ *
+ * @since 7.0.0
+ */
+export interface PrintBase64Options extends PrintOptions {
+    /**
+     * Valid base64 encoded string representing the file content.
+     *
+     * The base64 string should NOT include the data URL prefix (e.g., "data:application/pdf;base64,").
+     * Only provide the raw base64 encoded content.
+     *
+     * **Performance Considerations:**
+     * - Base64 encoding increases data size by approximately 33%
+     * - Large files (>5MB) may cause memory issues when decoding
+     * - Consider using printFile() for large documents
+     *
+     * **Platform Notes:**
+     * - **iOS**: Decoded to NSData and passed to UIPrintInteractionController
+     * - **Android**: Decoded to byte array and written to temporary file
+     * - **Web**: Converted to Blob for printing
+     *
+     * @since 7.0.0
+     * @example 'JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...'
+     */
+    data: string;
+    /**
+     * MIME type of the base64 encoded data.
+     *
+     * **Supported types:**
+     * - `application/pdf` - PDF documents
+     * - `image/jpeg` - JPEG images
+     * - `image/png` - PNG images
+     * - `image/gif` - GIF images (iOS/Android only)
+     * - `image/heic` - HEIC images (iOS only)
+     * - `image/heif` - HEIF images (iOS only)
+     *
+     * **Platform Support:**
+     * - All platforms support PDF, JPEG, and PNG
+     * - GIF support varies by platform
+     * - HEIC/HEIF are iOS-specific formats
+     *
+     * @since 7.0.0
+     * @example 'application/pdf'
+     * @example 'image/jpeg'
+     */
+    mimeType: string;
+}
+/**
+ * Options for printing files from device storage.
+ *
+ * @since 7.0.0
+ */
+export interface PrintFileOptions extends PrintOptions {
+    /**
+     * Path to the file to print.
+     *
+     * **iOS Path Formats:**
+     * - `file://` URL: Full file URL path
+     * - Relative path: Path relative to app's documents directory
+     * - Must be within app's accessible directories (documents, temporary, cache)
+     *
+     * **Android Path Formats:**
+     * - `content://` URI: Content provider URI (recommended for external files)
+     * - `file://` path: Direct file system path
+     * - Must have read permission for the file
+     *
+     * **Common Use Cases:**
+     * - App documents: Files saved in app's document directory
+     * - Downloads: Files from system downloads folder (use content:// on Android)
+     * - Temporary files: Files in app's temporary/cache directory
+     * - Shared storage: Files from external storage (Android, requires permissions)
+     *
+     * @since 7.0.0
+     * @platform ios Supports file:// paths and relative paths
+     * @platform android Supports content:// URIs and file:// paths
+     * @example 'content://com.android.providers.downloads.documents/document/123'
+     * @example 'file:///var/mobile/Containers/Data/Application/.../Documents/document.pdf'
+     * @example 'file:///storage/emulated/0/Download/receipt.pdf'
+     */
+    path: string;
+    /**
+     * MIME type of the file.
+     *
+     * **Platform Behavior:**
+     * - **Android**: REQUIRED for content:// URIs. Helps the system determine how to handle the file.
+     *                Optional for file:// paths (auto-detected from extension).
+     * - **iOS**: Ignored. File type is auto-detected from file extension.
+     * - **Web**: Optional. Auto-detected if not provided.
+     *
+     * **Common MIME Types:**
+     * - `application/pdf` - PDF documents
+     * - `image/jpeg` - JPEG images
+     * - `image/png` - PNG images
+     * - `image/gif` - GIF images
+     *
+     * @since 7.0.0
+     * @default Undefined (auto-detected from file extension)
+     * @platform android Used for content:// URIs and file type detection
+     * @platform ios Ignored (auto-detected)
+     * @example 'application/pdf'
+     * @example 'image/jpeg'
+     */
+    mimeType?: string;
+}
+/**
+ * Options for printing HTML content.
+ *
+ * @since 7.0.0
+ */
+export interface PrintHtmlOptions extends PrintOptions {
+    /**
+     * HTML content to print.
+     *
+     * **Content Requirements:**
+     * - Should be a complete HTML document with `<html>`, `<head>`, and `<body>` tags
+     * - Can include inline CSS styles or `<style>` tags
+     * - External resources (images, fonts) should use absolute URLs
+     * - JavaScript is not executed during print rendering
+     *
+     * **Print Optimization Tips:**
+     * - Use `@media print` CSS rules for print-specific styling
+     * - Control page breaks with `page-break-before`, `page-break-after`, `page-break-inside`
+     * - Hide UI elements using `.no-print { display: none; }` class
+     * - Adjust font sizes for readability (12pt is standard for print)
+     * - Use print-friendly colors (avoid dark backgrounds)
+     *
+     * **Platform Rendering:**
+     * - **iOS**: Rendered in WKWebView before printing
+     * - **Android**: Rendered in WebView before printing
+     * - **Web**: Rendered in hidden iframe before printing
+     *
+     * **Character Encoding:**
+     * - UTF-8 is recommended and default
+     * - Include charset in HTML: `<meta charset="UTF-8">`
+     *
+     * @since 7.0.0
+     * @example '<html><body><h1>Hello World</h1><p>This is a test document.</p></body></html>'
+     * @example
+     * ```typescript
+     * const htmlWithStyles = `
+     *   <html>
+     *     <head>
+     *       <meta charset="UTF-8">
+     *       <style>
+     *         @media print {
+     *           body { font-family: Arial, sans-serif; font-size: 12pt; }
+     *           .no-print { display: none; }
+     *           h1 { color: #333; page-break-before: always; }
+     *         }
+     *       </style>
+     *     </head>
+     *     <body>
+     *       <h1>Invoice #12345</h1>
+     *       <p>Amount: $299.99</p>
+     *     </body>
+     *   </html>
+     * `;
+     * ```
+     */
+    html: string;
+}
+/**
+ * Options for printing PDF documents.
+ *
+ * @since 7.0.0
+ */
+export interface PrintPdfOptions extends PrintOptions {
+    /**
+     * Path to the PDF document.
+     *
+     * **iOS Path Formats:**
+     * - `file://` URL: Full file URL path to PDF document
+     * - Relative path: Path relative to app's documents directory
+     * - Must be within app's accessible directories (documents, temporary, cache)
+     * - PDF must be valid and not password-protected
+     *
+     * **Android Path Formats:**
+     * - `content://` URI: Content provider URI (recommended for external PDFs)
+     * - `file://` path: Direct file system path to PDF
+     * - Must have read permission for the file
+     * - Supports both single-page and multi-page PDFs
+     *
+     * **Web Path Formats:**
+     * - Relative or absolute path accessible from web context
+     * - Must be a valid PDF file
+     *
+     * **Validation:**
+     * - File must exist at the specified path
+     * - File must be a valid PDF (checked by magic number/header)
+     * - File must be readable by the app
+     *
+     * **Common Sources:**
+     * - App documents: PDFs saved in app's document directory
+     * - Downloads: PDFs from system downloads (use content:// on Android)
+     * - Generated PDFs: Temporary PDFs created by the app
+     * - Network downloads: PDFs downloaded and saved locally
+     *
+     * @since 7.0.0
+     * @platform ios Supports file:// paths and relative paths
+     * @platform android Supports content:// URIs and file:// paths
+     * @platform web Supports accessible file paths
+     * @example 'content://com.android.providers.downloads.documents/document/123'
+     * @example 'file:///var/mobile/Containers/Data/Application/.../Documents/document.pdf'
+     * @example 'file:///storage/emulated/0/Download/report.pdf'
+     * @example 'Documents/invoice-2024.pdf'
+     */
+    path: string;
+}
+/**
+ * Base options for all print operations.
+ *
+ * @since 7.0.0
+ */
+export interface PrintOptions {
+    /**
+     * Name of the print job.
+     *
+     * **Usage:**
+     * - Displayed in the system print queue
+     * - Shown in print history/logs
+     * - May appear in printer status displays
+     * - Used as default filename for "Save as PDF" option
+     *
+     * **Platform Behavior:**
+     * - **iOS**: Shown in print preview header and activity view
+     * - **Android**: Displayed in print job notification and print queue
+     * - **Web**: Used as document title in print dialog
+     *
+     * **Best Practices:**
+     * - Use descriptive names (e.g., "Invoice #12345", "Q4 Report")
+     * - Keep under 50 characters for better display
+     * - Avoid special characters that may cause issues in filenames
+     * - Include relevant identifiers (order numbers, dates, etc.)
+     *
+     * **Examples:**
+     * - "Invoice #12345"
+     * - "Sales Report - 2024 Q4"
+     * - "Customer Receipt - John Doe"
+     * - "Product Photo - SKU-ABC123"
+     *
+     * @since 7.0.0
+     * @default 'Document'
+     * @platform ios Shown in print preview and activity view
+     * @platform android Shown in print queue and notifications
+     * @platform web Used as document title in print dialog
+     * @example 'Invoice #12345'
+     * @example 'Annual Report 2024'
+     * @example 'Receipt - Order #789'
+     */
+    name?: string;
+}
+/**
+ * Type alias for print web view options.
+ *
+ * @since 7.0.0
+ */
+export type PrintWebViewOptions = PrintOptions;

package/dist/esm/definitions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export interface PrinterPlugin {\n  /**\n   * Presents the printing UI to print files encoded as base64 strings.\n   *\n   * **Platform Behavior:**\n   * - **iOS**: Uses UIPrintInteractionController with base64 decoded data\n   * - **Android**: Uses PrintManager with base64 decoded data\n   * - **Web**: Creates a blob from base64 data and opens print dialog\n   *\n   * **Performance Warning:**\n   * Large files can lead to app crashes due to memory constraints when decoding base64.\n   * For files larger than 5MB, it's recommended to use printFile() instead.\n   *\n   * @param options - The base64 data and configuration for printing\n   * @returns Promise that resolves when print dialog is dismissed\n   * @throws Error if base64 data is invalid or printing fails\n   * @since 7.0.0\n   * @example\n   * ```typescript\n   * // Print a base64 encoded PDF\n   * await Printer.printBase64({\n   *   name: 'Invoice #12345',\n   *   data: 'JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...',\n   *   mimeType: 'application/pdf',\n   * });\n   *\n   * // Print a base64 encoded image\n   * await Printer.printBase64({\n   *   name: 'Product Photo',\n   *   data: '/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDA...',\n   *   mimeType: 'image/jpeg',\n   * });\n   * ```\n   */\n  printBase64(options: PrintBase64Options): Promise<void>;\n\n  /**\n   * Presents the printing UI to print device files.\n   *\n   * **Platform Behavior:**\n   * - **iOS**: Uses UIPrintInteractionController with file URL. Supports file:// paths or paths relative to app's documents directory.\n   * - **Android**: Uses PrintManager with file path. Supports both content:// URIs and file:// paths.\n   * - **Web**: Reads file and opens print dialog\n   *\n   * **Supported File Types:**\n   * - PDF documents (application/pdf)\n   * - Images: JPEG, PNG, GIF, HEIC, HEIF\n   *\n   * @param options - The file path and configuration for printing\n   * @returns Promise that resolves when print dialog is dismissed\n   * @throws Error if file path is invalid, file not found, or unsupported file type\n   * @since 7.0.0\n   * @example\n   * ```typescript\n   * // iOS: Print from app documents directory\n   * await Printer.printFile({\n   *   name: 'Contract',\n   *   path: 'file:///var/mobile/Containers/Data/Application/.../Documents/contract.pdf',\n   * });\n   *\n   * // Android: Print from content URI\n   * await Printer.printFile({\n   *   name: 'Receipt',\n   *   path: 'content://com.android.providers.downloads.documents/document/123',\n   *   mimeType: 'application/pdf',\n   * });\n   *\n   * // Android: Print from file path\n   * await Printer.printFile({\n   *   name: 'Photo',\n   *   path: 'file:///storage/emulated/0/Download/photo.jpg',\n   *   mimeType: 'image/jpeg',\n   * });\n   * ```\n   */\n  printFile(options: PrintFileOptions): Promise<void>;\n\n  /**\n   * Presents the printing UI to print HTML documents.\n   *\n   * **Platform Behavior:**\n   * - **iOS**: Renders HTML in WKWebView, then prints using UIPrintInteractionController\n   * - **Android**: Renders HTML in WebView, then prints using PrintManager\n   * - **Web**: Creates iframe with HTML content and triggers print dialog\n   *\n   * **HTML Requirements:**\n   * - Should be a complete HTML document with proper structure\n   * - Can include inline CSS styles or style tags\n   * - External resources (images, stylesheets) should use absolute URLs\n   * - Print-specific CSS can be added using @media print rules\n   *\n   * **CSS Print Styling:**\n   * Use CSS media queries to customize print output:\n   * - Control page breaks: page-break-before, page-break-after, page-break-inside\n   * - Hide elements: display: none for no-print classes\n   * - Adjust font sizes and colors for print\n   *\n   * @param options - The HTML content and configuration for printing\n   * @returns Promise that resolves when print dialog is dismissed\n   * @throws Error if HTML is invalid or printing fails\n   * @since 7.0.0\n   * @example\n   * ```typescript\n   * // Simple HTML document\n   * await Printer.printHtml({\n   *   name: 'Sales Report',\n   *   html: '<html><body><h1>Q4 Sales Report</h1><p>Revenue: $125,000</p></body></html>',\n   * });\n   *\n   * // HTML with print-specific CSS\n   * await Printer.printHtml({\n   *   name: 'Styled Invoice',\n   *   html: `\n   *     <html>\n   *       <head>\n   *         <style>\n   *           @media print {\n   *             body { font-size: 12pt; }\n   *             .no-print { display: none; }\n   *             h1 { page-break-before: always; }\n   *           }\n   *         </style>\n   *       </head>\n   *       <body>\n   *         <h1>Invoice #12345</h1>\n   *         <p>Amount due: $299.99</p>\n   *         <button class=\"no-print\">Don't print this button</button>\n   *       </body>\n   *     </html>\n   *   `,\n   * });\n   * ```\n   */\n  printHtml(options: PrintHtmlOptions): Promise<void>;\n\n  /**\n   * Presents the printing UI to print PDF documents.\n   *\n   * **Platform Behavior:**\n   * - **iOS**: Uses UIPrintInteractionController with PDF file URL\n   * - **Android**: Uses PrintManager with PdfDocument\n   * - **Web**: Creates object URL and opens print dialog\n   *\n   * **File Path Requirements:**\n   * - **iOS**: Must be file:// path or relative to app's documents directory\n   * - **Android**: Supports content:// URIs (from downloads, media store) or file:// paths\n   * - **Web**: Must be accessible file path\n   *\n   * @param options - The PDF file path and configuration for printing\n   * @returns Promise that resolves when print dialog is dismissed\n   * @throws Error if PDF path is invalid, file not found, or not a valid PDF\n   * @since 7.0.0\n   * @example\n   * ```typescript\n   * // Print PDF from app storage\n   * await Printer.printPdf({\n   *   name: 'Annual Report 2024',\n   *   path: 'file:///var/mobile/Containers/Data/Application/.../Documents/report.pdf',\n   * });\n   *\n   * // Print PDF from Android downloads\n   * await Printer.printPdf({\n   *   name: 'Downloaded Document',\n   *   path: 'content://com.android.providers.downloads.documents/document/123',\n   * });\n   * ```\n   */\n  printPdf(options: PrintPdfOptions): Promise<void>;\n\n  /**\n   * Presents the printing UI to print web view content.\n   *\n   * Prints the current content displayed in your app's web view.\n   *\n   * **Platform Behavior:**\n   * - **iOS**: Uses UIPrintInteractionController with WKWebView's view printable\n   * - **Android**: Uses WebView.createPrintDocumentAdapter() with PrintManager\n   * - **Web**: Triggers window.print() for current page\n   *\n   * **Print Styling:**\n   * Supports CSS print media queries for customization. The web view's current\n   * styles will be applied, including any @media print rules.\n   *\n   * **Use Cases:**\n   * - Print the current app screen/page\n   * - Print web-based reports or dashboards\n   * - Print user-generated content displayed in web view\n   *\n   * @param options - Optional configuration for printing (name only)\n   * @returns Promise that resolves when print dialog is dismissed\n   * @throws Error if web view is not available or printing fails\n   * @since 7.0.0\n   * @example\n   * ```typescript\n   * // Print current web view with default name\n   * await Printer.printWebView();\n   *\n   * // Print with custom job name\n   * await Printer.printWebView({\n   *   name: 'Dashboard Screenshot',\n   * });\n   *\n   * // Use with print-specific CSS in your HTML\n   * // Add this to your app's CSS:\n   * // @media print {\n   * //   .no-print { display: none; }\n   * //   body { font-size: 12pt; }\n   * // }\n   * await Printer.printWebView({\n   *   name: 'User Profile',\n   * });\n   * ```\n   */\n  printWebView(options?: PrintOptions): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version.\n   *\n   * Returns the hardcoded plugin version from native code (iOS/Android) or\n   * package version (Web). This is useful for debugging and ensuring plugin\n   * compatibility.\n   *\n   * @returns Promise that resolves with the plugin version string\n   * @throws Error if getting the version fails\n   * @since 7.0.0\n   * @example\n   * ```typescript\n   * const { version } = await Printer.getPluginVersion();\n   * console.log('Printer plugin version:', version);\n   * // Output: \"7.0.0\"\n   * ```\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n\n/**\n * Options for printing base64 encoded data.\n *\n * @since 7.0.0\n */\nexport interface PrintBase64Options extends PrintOptions {\n  /**\n   * Valid base64 encoded string representing the file content.\n   *\n   * The base64 string should NOT include the data URL prefix (e.g., \"data:application/pdf;base64,\").\n   * Only provide the raw base64 encoded content.\n   *\n   * **Performance Considerations:**\n   * - Base64 encoding increases data size by approximately 33%\n   * - Large files (>5MB) may cause memory issues when decoding\n   * - Consider using printFile() for large documents\n   *\n   * **Platform Notes:**\n   * - **iOS**: Decoded to NSData and passed to UIPrintInteractionController\n   * - **Android**: Decoded to byte array and written to temporary file\n   * - **Web**: Converted to Blob for printing\n   *\n   * @since 7.0.0\n   * @example 'JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...'\n   */\n  data: string;\n\n  /**\n   * MIME type of the base64 encoded data.\n   *\n   * **Supported types:**\n   * - `application/pdf` - PDF documents\n   * - `image/jpeg` - JPEG images\n   * - `image/png` - PNG images\n   * - `image/gif` - GIF images (iOS/Android only)\n   * - `image/heic` - HEIC images (iOS only)\n   * - `image/heif` - HEIF images (iOS only)\n   *\n   * **Platform Support:**\n   * - All platforms support PDF, JPEG, and PNG\n   * - GIF support varies by platform\n   * - HEIC/HEIF are iOS-specific formats\n   *\n   * @since 7.0.0\n   * @example 'application/pdf'\n   * @example 'image/jpeg'\n   */\n  mimeType: string;\n}\n\n/**\n * Options for printing files from device storage.\n *\n * @since 7.0.0\n */\nexport interface PrintFileOptions extends PrintOptions {\n  /**\n   * Path to the file to print.\n   *\n   * **iOS Path Formats:**\n   * - `file://` URL: Full file URL path\n   * - Relative path: Path relative to app's documents directory\n   * - Must be within app's accessible directories (documents, temporary, cache)\n   *\n   * **Android Path Formats:**\n   * - `content://` URI: Content provider URI (recommended for external files)\n   * - `file://` path: Direct file system path\n   * - Must have read permission for the file\n   *\n   * **Common Use Cases:**\n   * - App documents: Files saved in app's document directory\n   * - Downloads: Files from system downloads folder (use content:// on Android)\n   * - Temporary files: Files in app's temporary/cache directory\n   * - Shared storage: Files from external storage (Android, requires permissions)\n   *\n   * @since 7.0.0\n   * @platform ios Supports file:// paths and relative paths\n   * @platform android Supports content:// URIs and file:// paths\n   * @example 'content://com.android.providers.downloads.documents/document/123'\n   * @example 'file:///var/mobile/Containers/Data/Application/.../Documents/document.pdf'\n   * @example 'file:///storage/emulated/0/Download/receipt.pdf'\n   */\n  path: string;\n\n  /**\n   * MIME type of the file.\n   *\n   * **Platform Behavior:**\n   * - **Android**: REQUIRED for content:// URIs. Helps the system determine how to handle the file.\n   *                Optional for file:// paths (auto-detected from extension).\n   * - **iOS**: Ignored. File type is auto-detected from file extension.\n   * - **Web**: Optional. Auto-detected if not provided.\n   *\n   * **Common MIME Types:**\n   * - `application/pdf` - PDF documents\n   * - `image/jpeg` - JPEG images\n   * - `image/png` - PNG images\n   * - `image/gif` - GIF images\n   *\n   * @since 7.0.0\n   * @default Undefined (auto-detected from file extension)\n   * @platform android Used for content:// URIs and file type detection\n   * @platform ios Ignored (auto-detected)\n   * @example 'application/pdf'\n   * @example 'image/jpeg'\n   */\n  mimeType?: string;\n}\n\n/**\n * Options for printing HTML content.\n *\n * @since 7.0.0\n */\nexport interface PrintHtmlOptions extends PrintOptions {\n  /**\n   * HTML content to print.\n   *\n   * **Content Requirements:**\n   * - Should be a complete HTML document with `<html>`, `<head>`, and `<body>` tags\n   * - Can include inline CSS styles or `<style>` tags\n   * - External resources (images, fonts) should use absolute URLs\n   * - JavaScript is not executed during print rendering\n   *\n   * **Print Optimization Tips:**\n   * - Use `@media print` CSS rules for print-specific styling\n   * - Control page breaks with `page-break-before`, `page-break-after`, `page-break-inside`\n   * - Hide UI elements using `.no-print { display: none; }` class\n   * - Adjust font sizes for readability (12pt is standard for print)\n   * - Use print-friendly colors (avoid dark backgrounds)\n   *\n   * **Platform Rendering:**\n   * - **iOS**: Rendered in WKWebView before printing\n   * - **Android**: Rendered in WebView before printing\n   * - **Web**: Rendered in hidden iframe before printing\n   *\n   * **Character Encoding:**\n   * - UTF-8 is recommended and default\n   * - Include charset in HTML: `<meta charset=\"UTF-8\">`\n   *\n   * @since 7.0.0\n   * @example '<html><body><h1>Hello World</h1><p>This is a test document.</p></body></html>'\n   * @example\n   * ```typescript\n   * const htmlWithStyles = `\n   *   <html>\n   *     <head>\n   *       <meta charset=\"UTF-8\">\n   *       <style>\n   *         @media print {\n   *           body { font-family: Arial, sans-serif; font-size: 12pt; }\n   *           .no-print { display: none; }\n   *           h1 { color: #333; page-break-before: always; }\n   *         }\n   *       </style>\n   *     </head>\n   *     <body>\n   *       <h1>Invoice #12345</h1>\n   *       <p>Amount: $299.99</p>\n   *     </body>\n   *   </html>\n   * `;\n   * ```\n   */\n  html: string;\n}\n\n/**\n * Options for printing PDF documents.\n *\n * @since 7.0.0\n */\nexport interface PrintPdfOptions extends PrintOptions {\n  /**\n   * Path to the PDF document.\n   *\n   * **iOS Path Formats:**\n   * - `file://` URL: Full file URL path to PDF document\n   * - Relative path: Path relative to app's documents directory\n   * - Must be within app's accessible directories (documents, temporary, cache)\n   * - PDF must be valid and not password-protected\n   *\n   * **Android Path Formats:**\n   * - `content://` URI: Content provider URI (recommended for external PDFs)\n   * - `file://` path: Direct file system path to PDF\n   * - Must have read permission for the file\n   * - Supports both single-page and multi-page PDFs\n   *\n   * **Web Path Formats:**\n   * - Relative or absolute path accessible from web context\n   * - Must be a valid PDF file\n   *\n   * **Validation:**\n   * - File must exist at the specified path\n   * - File must be a valid PDF (checked by magic number/header)\n   * - File must be readable by the app\n   *\n   * **Common Sources:**\n   * - App documents: PDFs saved in app's document directory\n   * - Downloads: PDFs from system downloads (use content:// on Android)\n   * - Generated PDFs: Temporary PDFs created by the app\n   * - Network downloads: PDFs downloaded and saved locally\n   *\n   * @since 7.0.0\n   * @platform ios Supports file:// paths and relative paths\n   * @platform android Supports content:// URIs and file:// paths\n   * @platform web Supports accessible file paths\n   * @example 'content://com.android.providers.downloads.documents/document/123'\n   * @example 'file:///var/mobile/Containers/Data/Application/.../Documents/document.pdf'\n   * @example 'file:///storage/emulated/0/Download/report.pdf'\n   * @example 'Documents/invoice-2024.pdf'\n   */\n  path: string;\n}\n\n/**\n * Base options for all print operations.\n *\n * @since 7.0.0\n */\nexport interface PrintOptions {\n  /**\n   * Name of the print job.\n   *\n   * **Usage:**\n   * - Displayed in the system print queue\n   * - Shown in print history/logs\n   * - May appear in printer status displays\n   * - Used as default filename for \"Save as PDF\" option\n   *\n   * **Platform Behavior:**\n   * - **iOS**: Shown in print preview header and activity view\n   * - **Android**: Displayed in print job notification and print queue\n   * - **Web**: Used as document title in print dialog\n   *\n   * **Best Practices:**\n   * - Use descriptive names (e.g., \"Invoice #12345\", \"Q4 Report\")\n   * - Keep under 50 characters for better display\n   * - Avoid special characters that may cause issues in filenames\n   * - Include relevant identifiers (order numbers, dates, etc.)\n   *\n   * **Examples:**\n   * - \"Invoice #12345\"\n   * - \"Sales Report - 2024 Q4\"\n   * - \"Customer Receipt - John Doe\"\n   * - \"Product Photo - SKU-ABC123\"\n   *\n   * @since 7.0.0\n   * @default 'Document'\n   * @platform ios Shown in print preview and activity view\n   * @platform android Shown in print queue and notifications\n   * @platform web Used as document title in print dialog\n   * @example 'Invoice #12345'\n   * @example 'Annual Report 2024'\n   * @example 'Receipt - Order #789'\n   */\n  name?: string;\n}\n\n/**\n * Type alias for print web view options.\n *\n * @since 7.0.0\n */\nexport type PrintWebViewOptions = PrintOptions;\n"]}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+import type { PrinterPlugin } from './definitions';
+declare const Printer: PrinterPlugin;
+export * from './definitions';
+export { Printer };

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+import { registerPlugin } from '@capacitor/core';
+const Printer = registerPlugin('Printer', {
+    web: () => import('./web').then((m) => new m.PrinterWeb()),
+});
+export * from './definitions';
+export { Printer };
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,OAAO,GAAG,cAAc,CAAgB,SAAS,EAAE;IACvD,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;CAC3D,CAAC,CAAC;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,CAAC","sourcesContent":["import { registerPlugin } from '@capacitor/core';\n\nimport type { PrinterPlugin } from './definitions';\n\nconst Printer = registerPlugin<PrinterPlugin>('Printer', {\n  web: () => import('./web').then((m) => new m.PrinterWeb()),\n});\n\nexport * from './definitions';\nexport { Printer };\n"]}

package/dist/esm/web.d.ts

@@ -0,0 +1,13 @@
+import { WebPlugin } from '@capacitor/core';
+import type { PrintBase64Options, PrintFileOptions, PrintHtmlOptions, PrintOptions, PrintPdfOptions, PrinterPlugin } from './definitions';
+export declare class PrinterWeb extends WebPlugin implements PrinterPlugin {
+    printBase64(options: PrintBase64Options): Promise<void>;
+    printFile(options: PrintFileOptions): Promise<void>;
+    printHtml(options: PrintHtmlOptions): Promise<void>;
+    printPdf(options: PrintPdfOptions): Promise<void>;
+    printWebView(options?: PrintOptions): Promise<void>;
+    getPluginVersion(): Promise<{
+        version: string;
+    }>;
+    private printFromUrl;
+}

package/dist/esm/web.js

@@ -0,0 +1,106 @@
+import { WebPlugin } from '@capacitor/core';
+export class PrinterWeb extends WebPlugin {
+    async printBase64(options) {
+        const { data, mimeType, name } = options;
+        // Convert base64 to blob
+        const byteCharacters = atob(data);
+        const byteNumbers = new Array(byteCharacters.length);
+        for (let i = 0; i < byteCharacters.length; i++) {
+            byteNumbers[i] = byteCharacters.charCodeAt(i);
+        }
+        const byteArray = new Uint8Array(byteNumbers);
+        const blob = new Blob([byteArray], { type: mimeType });
+        // Create object URL and print
+        const url = URL.createObjectURL(blob);
+        await this.printFromUrl(url, name);
+        URL.revokeObjectURL(url);
+    }
+    async printFile(options) {
+        const { path, name } = options;
+        // On web, we can only print URLs that are accessible
+        // This will work for file:// URLs in some browsers or HTTP(S) URLs
+        await this.printFromUrl(path, name);
+    }
+    async printHtml(options) {
+        const { html, name } = options;
+        // Create a blob URL from the HTML content
+        const blob = new Blob([html], { type: 'text/html' });
+        const url = URL.createObjectURL(blob);
+        await this.printFromUrl(url, name);
+        URL.revokeObjectURL(url);
+    }
+    async printPdf(options) {
+        const { path, name } = options;
+        // On web, print the PDF URL
+        await this.printFromUrl(path, name);
+    }
+    async printWebView(options) {
+        // Set document title for print job name
+        const originalTitle = document.title;
+        if (options === null || options === void 0 ? void 0 : options.name) {
+            document.title = options.name;
+        }
+        // Trigger browser print dialog
+        window.print();
+        // Restore original title
+        document.title = originalTitle;
+    }
+    async getPluginVersion() {
+        return { version: '7.0.0' };
+    }
+    async printFromUrl(url, name) {
+        return new Promise((resolve, reject) => {
+            // Create hidden iframe
+            const iframe = document.createElement('iframe');
+            iframe.style.position = 'fixed';
+            iframe.style.right = '0';
+            iframe.style.bottom = '0';
+            iframe.style.width = '0';
+            iframe.style.height = '0';
+            iframe.style.border = 'none';
+            // Set up load handler
+            iframe.onload = () => {
+                try {
+                    // Set document title if name provided
+                    if (name && iframe.contentDocument) {
+                        iframe.contentDocument.title = name;
+                    }
+                    // Small delay to ensure content is loaded
+                    setTimeout(() => {
+                        try {
+                            // Try to access the iframe's window
+                            const iframeWindow = iframe.contentWindow;
+                            if (!iframeWindow) {
+                                throw new Error('Cannot access iframe window');
+                            }
+                            // Print the iframe content
+                            iframeWindow.focus();
+                            iframeWindow.print();
+                            // Clean up after a delay
+                            setTimeout(() => {
+                                document.body.removeChild(iframe);
+                                resolve();
+                            }, 100);
+                        }
+                        catch (error) {
+                            document.body.removeChild(iframe);
+                            reject(error);
+                        }
+                    }, 100);
+                }
+                catch (error) {
+                    document.body.removeChild(iframe);
+                    reject(error);
+                }
+            };
+            iframe.onerror = () => {
+                document.body.removeChild(iframe);
+                reject(new Error('Failed to load content for printing'));
+            };
+            // Add iframe to document and set source
+            document.body.appendChild(iframe);
+            iframe.src = url;
+        });
+    }
+}
+//# sourceMappingURL=web.js.map