@plevands/epson-thermal-printer 0.1.1

package/dist/lib/epos-print.d.ts

@@ -0,0 +1,140 @@
+import { epson } from './epson-sdk';
+import { loadEpsonSDK, isEpsonSDKLoaded, getLoaderState, initializeEpsonSDK } from './epson-sdk-loader';
+import { EpsonPrinterConfig, PrintResult, PrintOptions } from '../types';
+export type { EpsonPrinterConfig, PrintResult, PrintOptions } from '../types';
+export { loadEpsonSDK, isEpsonSDKLoaded, initializeEpsonSDK, getLoaderState, };
+/**
+ * Check SDK status - useful for debugging
+ */
+export declare function checkEpsonSDKStatus(): {
+    loaded: boolean;
+    loading: boolean;
+    error: Error | null;
+    classes: string[];
+};
+/**
+ * ePOS Print Service using official SDK
+ */
+export declare class EposPrintService {
+    private config;
+    private printOptions;
+    private initPromise;
+    constructor(config: EpsonPrinterConfig, options?: PrintOptions);
+    /**
+     * Ensure SDK is loaded before any print operation (lazy loading)
+     */
+    private ensureSDKLoaded;
+    /**
+     * Get the printer URL for ePOS Print
+     */
+    private getPrinterUrl;
+    /**
+     * Print a canvas element using ePOSBuilder
+     *
+     * IMPORTANT: We don't use CanvasPrint.print() directly due to an SDK bug.
+     * The SDK's prototypal inheritance causes CanvasPrint.print() to call
+     * this.send(printjobid) which internally creates a new empty ePOSBuilder,
+     * ignoring all the commands built in 'this'.
+     *
+     * Instead, we use ePOSBuilder to construct the print commands manually,
+     * get the XML, and send it via ePOSPrint.send(xml).
+     */
+    printCanvas(canvas: HTMLCanvasElement): Promise<PrintResult>;
+    /**
+     * Get alignment value for SDK (instance property values are strings)
+     */
+    private getAlignValue;
+    /**
+     * Print using ePOSPrint with builder pattern
+     */
+    printWithBuilder(buildFn: (builder: epson.ePOSBuilder) => void): Promise<PrintResult>;
+    /**
+     * Print multiple canvases (pages) with optional header/footer
+     */
+    printPages(canvases: HTMLCanvasElement[], options?: {
+        header?: string;
+        footer?: string;
+        pageSeparator?: boolean;
+    }): Promise<PrintResult>;
+    /**
+     * Check printer connection without printing anything.
+     * Sends a status request to verify the printer is online and responding.
+     *
+     * @returns Promise with connection result
+     *
+     * @example
+     * ```typescript
+     * const service = new EposPrintService(config);
+     * const result = await service.checkConnection();
+     *
+     * if (result.success) {
+     *   console.log('Printer is online!');
+     * } else {
+     *   console.log('Printer offline:', result.message);
+     * }
+     * ```
+     */
+    checkConnection(): Promise<PrintResult>;
+    /**
+     * Get human-readable message for printer status code
+     */
+    private getStatusMessage;
+    /**
+     * Test printer connection by printing a small test receipt.
+     * Use `checkConnection()` if you want to test without printing.
+     */
+    testConnection(): Promise<PrintResult>;
+    /**
+     * Print a test page
+     */
+    printTestPage(): Promise<PrintResult>;
+}
+/**
+ * PDF to Canvas conversion utilities
+ */
+export declare function pdfToCanvases(pdfFile: File, options?: {
+    scale?: number;
+    maxWidth?: number;
+}): Promise<{
+    canvas: HTMLCanvasElement;
+    width: number;
+    height: number;
+}[]>;
+/**
+ * Convert image file to canvas
+ */
+export declare function imageToCanvas(file: File, maxWidth?: number): Promise<{
+    canvas: HTMLCanvasElement;
+    width: number;
+    height: number;
+}>;
+export declare class EposPrintBuilder {
+    private builder;
+    constructor();
+    reset(): this;
+    addText(text: string): this;
+    addTextLine(text: string): this;
+    addFeedLine(lines?: number): this;
+    addCut(type?: 'no_feed' | 'feed' | 'reserve'): this;
+    addTextAlign(align: 'left' | 'center' | 'right'): this;
+    addTextStyle(reverse?: boolean, underline?: boolean, bold?: boolean, color?: 'color_1' | 'color_2' | 'color_3' | 'color_4'): this;
+    addTextSize(width?: number, height?: number): this;
+    addImage(canvas: HTMLCanvasElement, mode?: 'mono' | 'gray16'): this;
+    addBarcode(data: string, type?: string, hri?: 'none' | 'above' | 'below' | 'both', width?: number, height?: number): this;
+    addQRCode(data: string, type?: 'model_1' | 'model_2' | 'micro', level?: 'level_l' | 'level_m' | 'level_q' | 'level_h', width?: number): this;
+    build(): string;
+    getBuilder(): epson.ePOSBuilder;
+}
+export declare function pdfToImages(pdfFile: File, options?: {
+    scale?: number;
+    maxWidth?: number;
+}): Promise<{
+    images: string[];
+    width: number;
+    height: number;
+}[]>;
+export declare function imageToBase64(file: File): Promise<{
+    base64: string;
+    width: number;
+    height: number;
+}>;

package/dist/lib/epson-sdk-loader.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Dynamic loader for Epson ePOS SDK
+ * Implements singleton pattern to avoid multiple loads
+ */
+interface LoaderState {
+    loading: boolean;
+    loaded: boolean;
+    error: Error | null;
+    promise: Promise<boolean> | null;
+}
+/**
+ * Check if SDK is already available in window
+ */
+export declare function isEpsonSDKLoaded(): boolean;
+/**
+ * Load Epson SDK dynamically (singleton pattern)
+ * Returns true if loaded successfully, false otherwise
+ */
+export declare function loadEpsonSDK(options?: {
+    timeout?: number;
+}): Promise<boolean>;
+/**
+ * Get current loader state
+ */
+export declare function getLoaderState(): Readonly<LoaderState>;
+/**
+ * Reset loader state (useful for testing)
+ */
+export declare function resetLoaderState(): void;
+/**
+ * Get Epson SDK (throws if not loaded)
+ */
+export declare function getEpsonSDK(): typeof window.epson;
+/**
+ * Initialize SDK (optional - for eager loading)
+ */
+export declare function initializeEpsonSDK(options?: {
+    sdkPath?: string;
+    timeout?: number;
+}): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+export {};

package/dist/lib/logger.d.ts

@@ -0,0 +1,29 @@
+import { LoggerConfig } from '../types';
+/**
+ * Configure the logger
+ * @param newConfig - Logger configuration options
+ */
+export declare function configureLogger(newConfig: Partial<LoggerConfig>): void;
+/**
+ * Get current logger configuration
+ */
+export declare function getLoggerConfig(): Readonly<LoggerConfig>;
+/**
+ * Log debug message (only when enabled)
+ */
+export declare function debug(message: string, ...args: unknown[]): void;
+/**
+ * Log warning message (only when enabled)
+ */
+export declare function warn(message: string, ...args: unknown[]): void;
+/**
+ * Log error message (always shown)
+ */
+export declare function error(message: string, ...args: unknown[]): void;
+export declare const logger: {
+    debug: typeof debug;
+    warn: typeof warn;
+    error: typeof error;
+    configure: typeof configureLogger;
+    getConfig: typeof getLoggerConfig;
+};

package/dist/lib/pdf-processor.d.ts

@@ -0,0 +1,101 @@
+import { PDFPageProxy } from 'pdfjs-dist';
+/** Default CDN URL for PDF.js worker (version appended after loading) */
+export declare const PDFJS_CDN_WORKER_BASE = "https://unpkg.com/pdfjs-dist@";
+/** Full CDN URL (populated after loading pdfjs-dist) */
+export declare let PDFJS_CDN_WORKER_URL: string;
+/**
+ * Error thrown when pdfjs-dist is not installed
+ */
+export declare class PdfJsNotInstalledError extends Error {
+    constructor();
+}
+/**
+ * Check if pdfjs-dist is available (installed).
+ * Useful to check before calling PDF functions.
+ *
+ * @returns Promise that resolves to true if pdfjs-dist is available
+ *
+ * @example
+ * ```typescript
+ * if (await isPdfJsAvailable()) {
+ *   const pages = await processPdfFile(file);
+ * } else {
+ *   console.log('PDF processing not available. Install pdfjs-dist to enable.');
+ * }
+ * ```
+ */
+export declare function isPdfJsAvailable(): Promise<boolean>;
+/**
+ * Configure PDF.js worker source.
+ * Call this BEFORE using any PDF processing functions.
+ * If not called, the worker will be loaded from CDN automatically.
+ *
+ * @param workerSrc - URL to the PDF.js worker.
+ *
+ * @example
+ * ```typescript
+ * // Use your own worker instead of CDN
+ * configurePdfWorker('/assets/pdf.worker.min.mjs');
+ * ```
+ */
+export declare function configurePdfWorker(workerSrc: string): void;
+/**
+ * Check if PDF.js worker is configured
+ */
+export declare function isPdfWorkerConfigured(): boolean;
+export interface PdfProcessingConfig {
+    /** Enable PDF processing (trimming, scaling) */
+    enabled: boolean;
+    /** Margin settings for trimming white space */
+    trimMargins?: {
+        top?: number;
+        bottom?: number;
+        left?: number;
+        right?: number;
+    };
+    /** Target width for printer paper (576 for 80mm, 384 for 58mm) */
+    targetWidth?: number;
+    /** Rendering scale for quality (higher = better quality) */
+    scale?: number;
+    /** Threshold for monochrome conversion (0-255, lower = darker) */
+    monochromeThreshold?: number;
+}
+export interface ProcessedPage {
+    base64: string;
+    width: number;
+    height: number;
+    rasterBase64: string;
+    canvas: HTMLCanvasElement;
+}
+/**
+ * Default configuration for PDF processing
+ */
+export declare const DEFAULT_PDF_CONFIG: Required<PdfProcessingConfig>;
+/**
+ * Process a PDF page to canvas with optional trimming and scaling
+ */
+export declare function processPdfPage(page: PDFPageProxy, config?: PdfProcessingConfig): Promise<ProcessedPage>;
+/**
+ * Process all pages of a PDF file.
+ *
+ * @remarks
+ * Requires `pdfjs-dist` to be installed:
+ * ```bash
+ * npm install pdfjs-dist
+ * ```
+ *
+ * @param file - PDF file to process
+ * @param config - Processing configuration
+ * @returns Promise with array of processed pages
+ * @throws {PdfJsNotInstalledError} If pdfjs-dist is not installed
+ *
+ * @example
+ * ```typescript
+ * const pages = await processPdfFile(file, {
+ *   enabled: true,
+ *   targetWidth: 576, // 80mm paper
+ *   trimMargins: { top: 10, bottom: 10, left: 5, right: 5 },
+ * });
+ * ```
+ */
+export declare function processPdfFile(file: File, config?: PdfProcessingConfig): Promise<ProcessedPage[]>;

package/dist/types/index.d.ts

@@ -0,0 +1,86 @@
+import { ProcessedPage } from '../lib/pdf-processor';
+/**
+ * Type definitions for @plevands/epson-thermal-printer library
+ */
+export type { PdfProcessingConfig, ProcessedPage } from '../lib/pdf-processor';
+export interface EpsonPrinterConfig {
+    printerIP: string;
+    printerPort?: number;
+    deviceId?: string;
+    timeout?: number;
+}
+export interface PrintResult {
+    success: boolean;
+    code?: string;
+    status?: number;
+    message?: string;
+    printjobid?: string;
+}
+export interface PrintOptions {
+    halftone?: 0 | 1 | 2;
+    brightness?: number;
+    mode?: 'mono' | 'gray16';
+    cut?: boolean;
+    align?: 'left' | 'center' | 'right';
+}
+export interface LoaderState {
+    loading: boolean;
+    loaded: boolean;
+    error: Error | null;
+}
+export interface SDKLoadOptions {
+    timeout?: number;
+}
+export interface InitializeSDKResult {
+    success: boolean;
+    error?: string;
+}
+export interface PrinterStatus {
+    loaded: boolean;
+    loading: boolean;
+    error: Error | null;
+    classes: string[];
+}
+export interface UseEpsonPrinterReturn {
+    /** Print a single canvas to the thermal printer */
+    print: (canvas: HTMLCanvasElement) => Promise<PrintResult>;
+    /** Print multiple canvases (pages) with optional page selection */
+    printPages: (canvases: HTMLCanvasElement[], options?: {
+        pageSelection?: 'all' | number[];
+        headerText?: string;
+        footerText?: string;
+    }) => Promise<PrintResult>;
+    /** Check printer connection without printing anything */
+    checkConnection: () => Promise<PrintResult>;
+    /** Test printer connection by printing a small test receipt */
+    testConnection: () => Promise<PrintResult>;
+    /** Whether a print operation is in progress */
+    isLoading: boolean;
+    /** Error message from the last operation, if any */
+    error: string | null;
+    /** Current SDK loading status */
+    sdkStatus: PrinterStatus;
+}
+export interface UsePrinterConfigReturn {
+    config: EpsonPrinterConfig;
+    updateConfig: (newConfig: Partial<EpsonPrinterConfig>) => void;
+    resetConfig: () => void;
+    isConfigured: boolean;
+}
+export interface UsePdfProcessorReturn {
+    processFile: (file: File) => Promise<ProcessedPage[]>;
+    isProcessing: boolean;
+    error: string | null;
+}
+export type LogLevel = 'debug' | 'warn' | 'error';
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    args?: unknown[];
+}
+export interface LoggerConfig {
+    /** Enable debug/warn logs in console (errors always shown). Default: false */
+    enabled: boolean;
+    /** Callback to intercept all logs (including errors) */
+    onLog?: (entry: LogEntry) => void;
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@plevands/epson-thermal-printer",
+  "version": "0.1.1",
+  "description": "Library for Epson thermal printer integration with PDF support and React hooks",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/*.js",
+    "dist/*.cjs",
+    "dist/*.d.ts",
+    "dist/hooks",
+    "dist/lib",
+    "dist/types",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plevands/epson-thermal-printer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/plevands/epson-thermal-printer/issues"
+  },
+  "homepage": "https://github.com/plevands/epson-thermal-printer#readme",
+  "scripts": {
+    "dev": "vite --host --port 5123",
+    "build": "tsc -b && vite build",
+    "dev:lib": "vite build --watch",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "pdfjs-dist": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "pdfjs-dist": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "npm:rolldown-vite@7.2.5",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "overrides": {
+    "vite": "npm:rolldown-vite@7.2.5"
+  },
+  "keywords": [
+    "epson",
+    "printer",
+    "thermal-printer",
+    "epos",
+    "pdf",
+    "react",
+    "typescript"
+  ],
+  "author": "Colegio Plevand's",
+  "license": "MIT"
+}