@esslassi/electron-printer 0.0.6 → 0.0.8

package/README.md

@@ -1,251 +1,319 @@
-Here is the clean **README.md** content ready to copy and paste:
+# 📦 @esslassi/electron-printer
 
----
+Cross-platform native printer driver for **Windows, macOS, and Linux**, built with Node-API (N-API).
+Works in **Node.js** and **Electron**.
 
-# Electron Printer (@esslassi/electron-printer)
+Supports:
 
-Node.js and Electron bindings for printer management and direct printing. Supports Windows and Linux (CUPS).
+* 🖨 List printers
+* 📄 Print raw/text/command data
+* 📁 Print files
+* 📋 Get printer driver options
+* 📑 Get selected paper size
+* 📦 Get job status
+* ⛔ Cancel / pause / resume jobs
+* 🔄 Promise (async/await) wrappers included
 
-## Features
+---
 
-* List all available printers
-* Get the system default printer
-* Get detailed printer status
-* Direct printing (raw printing)
-* TypeScript support
-* Asynchronous API (Promises)
-* Compatible with Node.js and Electron
+## 🚀 Installation
 
-## Requirements
+```bash
+npm install @esslassi/electron-printer
+```
 
-* Node.js >= 18.20.6
-* Electron >= 20.0.0
-* Windows or Linux
-* For Windows: Visual Studio Build Tools
-* For Linux: CUPS development headers
+If using Electron:
 
 ```bash
-sudo apt-get install libcups2-dev
+npx electron-rebuild
 ```
 
-## Installation
+---
+
+## 🧩 Supported Platforms
 
-```bash
-npm install @esslassi/electron-printer
+| OS      | Backend      |
+| ------- | ------------ |
+| Windows | WinSpool API |
+| macOS   | CUPS         |
+| Linux   | CUPS         |
+
+---
+
+# 📖 Usage
+
+```ts
+import * as printer from '@esslassi/electron-printer'
 ```
 
-For development:
+---
 
-```bash
-git clone https://github.com/esslassi/electron-printer.git
-cd electron-printer
-npm install
-npm run rebuild
+# 🖨 Printer Management
+
+### Get all printers
+
+```ts
+const printers = printer.getPrinters()
 ```
 
-## Usage
+### Async version
 
-### JavaScript
+```ts
+const printers = await printer.getPrintersAsync()
+```
 
-```javascript
-const printer = require('@esslassi/electron-printer');
+---
 
-// List all printers
-printer.getPrinters()
-  .then(printers => {
-    console.log('Available printers:', printers);
-  })
-  .catch(console.error);
+### Get single printer
 
-// Get default printer
-printer.getDefaultPrinter()
-  .then(defaultPrinter => {
-    console.log('Default printer:', defaultPrinter);
-  })
-  .catch(console.error);
+```ts
+const details = printer.getPrinter("My Printer")
+```
 
-// Check printer status
-printer.getStatusPrinter({ printerName: 'Printer Name' })
-  .then(status => {
-    console.log('Printer status:', status);
-  })
-  .catch(console.error);
-
-// Print directly
-const printOptions = {
-  printerName: 'Printer Name',
-  data: 'Text to print',
-  dataType: 'RAW' // optional (default is 'RAW')
-};
-
-printer.printDirect(printOptions)
-  .then(result => {
-    console.log('Result:', result);
-  })
-  .catch(console.error);
+---
+
+### Get default printer
+
+```ts
+const defaultPrinter = printer.getDefaultPrinterName()
 ```
 
-### TypeScript
+---
+
+### Get printer driver options
 
-```typescript
-import printer, { 
-  Printer, 
-  PrintDirectOptions, 
-  GetStatusPrinterOptions 
-} from '@esslassi/electron-printer';
+```ts
+const options = printer.getPrinterDriverOptions("My Printer")
+```
+
+---
 
-async function example() {
-  try {
-    const printers: Printer[] = await printer.getPrinters();
-    console.log('Printers:', printers);
+### Get selected paper size
 
-    const defaultPrinter: Printer = await printer.getDefaultPrinter();
-    console.log('Default printer:', defaultPrinter);
+```ts
+const paper = printer.getSelectedPaperSize("My Printer")
+```
 
-    const statusOptions: GetStatusPrinterOptions = {
-      printerName: 'Printer Name'
-    };
-    const status: Printer = await printer.getStatusPrinter(statusOptions);
-    console.log('Status:', status);
+---
 
-    const printOptions: PrintDirectOptions = {
-      printerName: 'Printer Name',
-      data: Buffer.from('Text to print'),
-      dataType: 'RAW'
-    };
+# 🖨 Printing
 
-    const result = await printer.printDirect(printOptions);
-    console.log('Result:', result);
+---
 
-  } catch (error) {
-    console.error('Error:', error);
+## 🟢 Print Raw/Text Data (Callback)
+
+```ts
+printer.printDirect({
+  data: "Hello Printer\n\n",
+  printer: "My Printer",
+  type: "RAW",
+  success: (jobId) => {
+    console.log("Printed. Job ID:", jobId)
+  },
+  error: (err) => {
+    console.error("Print error:", err)
   }
-}
+})
 ```
 
-## API
+---
 
-### getPrinters(): Promise<Printer[]>
+## 🟢 Print Raw/Text Data (Async/Await)
 
-Lists all printers installed on the system.
+```ts
+const jobId = await printer.printDirectAsync({
+  data: Buffer.from("Hello Printer\n\n"),
+  printer: "My Printer",
+  type: "RAW"
+})
 
-```typescript
-interface Printer {
-  name: string;
-  isDefault: boolean;
-  status: string;
-  details: {
-    location?: string;
-    comment?: string;
-    driver?: string;
-    port?: string;
-    [key: string]: string | undefined;
-  };
-}
+console.log("Printed. Job ID:", jobId)
 ```
 
 ---
 
-### getDefaultPrinter(): Promise<Printer>
+## 🟢 Print File (Callback)
 
-Returns the system default printer.
+```ts
+printer.printFile({
+  filename: "./file.txt",
+  printer: "My Printer",
+  success: (jobId) => console.log(jobId),
+  error: (err) => console.error(err)
+})
+```
 
 ---
 
-### getStatusPrinter(options: GetStatusPrinterOptions): Promise<Printer>
+## 🟢 Print File (Async)
 
-```typescript
-interface GetStatusPrinterOptions {
-  printerName: string;
-}
+```ts
+const jobId = await printer.printFileAsync({
+  filename: "./file.txt",
+  printer: "My Printer"
+})
 ```
 
 ---
 
-### printDirect(options: PrintDirectOptions): Promise<string>
+# 📦 Job Management
 
-```typescript
-interface PrintDirectOptions {
-  printerName: string;
-  data: string | Buffer;
-  dataType?: 'RAW' | 'TEXT' | 'COMMAND' | 'AUTO';
-}
+---
+
+## Get Job Details
+
+```ts
+const job = printer.getJob("My Printer", 42)
+```
+
+### Async
+
+```ts
+const job = await printer.getJobAsync("My Printer", 42)
 ```
 
-### Possible Status Values
+---
+
+## Cancel / Pause / Resume Job
 
-* ready
-* offline
-* error
-* paper-jam
-* paper-out
-* manual-feed
-* paper-problem
-* busy
-* printing
-* output-bin-full
-* not-available
-* waiting
-* processing
-* initializing
-* warming-up
-* toner-low
-* no-toner
-* page-punt
-* user-intervention
-* out-of-memory
-* door-open
+```ts
+printer.setJob("My Printer", 42, "CANCEL")
+printer.setJob("My Printer", 42, "PAUSE")
+printer.setJob("My Printer", 42, "RESUME")
+```
 
 ---
 
-## Supported Platforms
+## Get Supported Job Commands
 
-* Windows (32/64-bit)
-* Linux (CUPS)
+```ts
+const commands = printer.getSupportedJobCommands()
+```
 
 ---
 
-## Troubleshooting
+# 📄 Supported Print Formats
+
+```ts
+const formats = printer.getSupportedPrintFormats()
+```
 
-### Windows
+Typical values:
 
-1. Install Visual Studio Build Tools
-2. Run:
+* `RAW`
+* `TEXT`
+* `COMMAND`
+* `AUTO`
 
-```bash
-npm run rebuild
+> Windows supports RAW/TEXT/COMMAND directly.
+> macOS/Linux support additional formats via CUPS.
+
+---
+
+# 🧠 TypeScript Types
+
+Fully typed. Example:
+
+```ts
+export interface PrintDirectOptions {
+  data: string | Buffer
+  printer?: string
+  type?: 'RAW' | 'TEXT' | 'COMMAND' | 'AUTO'
+  options?: { [key: string]: string }
+}
 ```
 
-3. Verify printer access permissions
+---
+
+# ⚡ Promise Wrappers Included
 
-### Linux
+Built-in async wrappers:
 
-```bash
-sudo apt-get install libcups2-dev
-sudo service cups status
-sudo usermod -a -G lp $USER
+* `printDirectAsync`
+* `printFileAsync`
+* `getPrintersAsync`
+* `getPrinterAsync`
+* `getJobAsync`
+
+No extra wrapper needed.
+
+---
+
+# 🧪 Example Full Test
+
+```ts
+import * as printer from '@esslassi/electron-printer'
+
+async function test() {
+  const printers = await printer.getPrintersAsync()
+  const defaultPrinter = printer.getDefaultPrinterName()
+
+  const jobId = await printer.printDirectAsync({
+    data: "Test print\n\n",
+    printer: defaultPrinter,
+    type: "RAW"
+  })
+
+  const job = await printer.getJobAsync(defaultPrinter!, Number(jobId))
+
+  console.log(job)
+}
+
+test()
 ```
 
 ---
 
-## Development
+# 🏗 Architecture
+
+```
+Node.js / Electron
+        ↓
+N-API
+        ↓
+PrinterFactory
+        ↓
+Windows | macOS | Linux drivers
+```
+
+Native C++ backend with platform-specific implementations.
+
+---
+
+# 🔧 Development
+
+Build from source:
+
+```bash
+npx node-gyp rebuild
+```
+
+Electron:
 
 ```bash
-git clone https://github.com/esslassi/electron-printer.git
-cd electron-printer
-npm install
-npm run rebuild
-node test.js
+npx electron-rebuild
 ```
 
 ---
 
-## License
+# 📜 License
 
 MIT
 
 ---
 
-## Author
+# 👨‍💻 Author
+
+Esslassi
+
+---
+
+If you want, I can also generate:
+
+* 🔥 NPM package.json template
+* 🧱 binding.gyp optimized version
+* ⚡ Prebuild support (no node-gyp required for users)
+* 🧪 Jest test suite
+* 📦 CLI tool version
 
-Esslassi
+Tell me the next step 🚀

package/lib/electronPrinter.d.ts

@@ -1,33 +1,61 @@
-export interface PrintOptions {
-    printerName: string;
+export type PrintOnSuccessFunction = (jobId: string) => any;
+export type PrintOnErrorFunction = (err: Error) => any;
+export interface PrintDirectOptions {
     data: string | Buffer;
-    dataType?: 'RAW' | 'TEXT' | 'COMMAND' | 'AUTO' | undefined;
+    printer?: string;
+    type?: 'RAW' | 'TEXT' | 'COMMAND' | 'AUTO';
+    options?: {
+        [key: string]: string;
+    };
+    success?: PrintOnSuccessFunction;
+    error?: PrintOnErrorFunction;
 }
-export interface Printer {
+export interface PrintFileOptions {
+    filename: string;
+    printer?: string;
+    success?: PrintOnSuccessFunction;
+    error?: PrintOnErrorFunction;
+}
+export interface PrinterDetails {
     name: string;
     isDefault: boolean;
-    status: string;
-    details: {
-        location?: string;
-        comment?: string;
-        driver?: string;
-        port?: string;
-        [key: string]: string | undefined;
+    options: {
+        [key: string]: string;
     };
 }
-export interface PrintDirectOptions {
-    printerName: string;
-    data: string | Buffer;
-    dataType?: 'RAW' | 'TEXT' | 'COMMAND' | 'AUTO' | undefined;
-}
-export interface GetStatusPrinterOptions {
-    printerName: string;
+export interface PrinterDriverOptions {
+    [key: string]: {
+        [key: string]: boolean;
+    };
 }
-export interface PrintDirectOutput {
+export type JobStatus = 'PAUSED' | 'PRINTING' | 'PRINTED' | 'CANCELLED' | 'PENDING' | 'ABORTED';
+export type JobCommand = "CANCEL" | "PAUSE" | "RESUME";
+export interface JobDetails {
+    id: number;
     name: string;
-    status: 'success' | 'failed';
+    printerName: string;
+    user: string;
+    format: string;
+    priority: number;
+    size: number;
+    status: JobStatus[];
+    completedTime: Date;
+    creationTime: Date;
+    processingTime: Date;
 }
-export declare function printDirect(printOptions: PrintOptions): Promise<PrintDirectOutput>;
-export declare function getStatusPrinter(printOptions: GetStatusPrinterOptions): Promise<Printer>;
-export declare function getPrinters(): Promise<Printer[]>;
-export declare function getDefaultPrinter(): Promise<Printer>;
+export declare function getPrinters(): PrinterDetails[];
+export declare function getPrinter(printerName: string): PrinterDetails;
+export declare function getPrinterDriverOptions(printerName: string): PrinterDriverOptions;
+export declare function getSelectedPaperSize(printerName: string): string;
+export declare function getDefaultPrinterName(): string | undefined;
+export declare function printDirect(options: PrintDirectOptions): void;
+export declare function printFile(options: PrintFileOptions): void;
+export declare function getSupportedPrintFormats(): string[];
+export declare function getJob(printerName: string, jobId: number): JobDetails;
+export declare function setJob(printerName: string, jobId: number, command: JobCommand): void;
+export declare function getSupportedJobCommands(): string[];
+export declare function printDirectAsync(options: Omit<PrintDirectOptions, 'success' | 'error'>): Promise<string>;
+export declare function printFileAsync(options: Omit<PrintFileOptions, 'success' | 'error'>): Promise<string>;
+export declare function getJobAsync(printerName: string, jobId: number): Promise<JobDetails>;
+export declare function getPrintersAsync(): Promise<PrinterDetails[]>;
+export declare function getPrinterAsync(printerName: string): Promise<PrinterDetails>;

package/lib/electronPrinter.js

@@ -3,36 +3,87 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.printDirect = printDirect;
-exports.getStatusPrinter = getStatusPrinter;
 exports.getPrinters = getPrinters;
-exports.getDefaultPrinter = getDefaultPrinter;
-const bindings_1 = __importDefault(require("bindings"));
-const electronPrinter = (0, bindings_1.default)('electron_printer');
-async function printDirect(printOptions) {
-    const input = {
-        ...printOptions,
-        printerName: normalizeString(printOptions.printerName)
-    };
-    const printer = await electronPrinter.printDirect(input);
-    return printer;
-}
-async function getStatusPrinter(printOptions) {
-    const input = {
-        ...printOptions,
-        printerName: normalizeString(printOptions.printerName)
-    };
-    const printer = await electronPrinter.getStatusPrinter(input);
-    return printer;
-}
-async function getPrinters() {
-    const printers = await electronPrinter.getPrinters();
-    return printers;
-}
-async function getDefaultPrinter() {
-    const printer = await electronPrinter.getDefaultPrinter();
-    return printer;
-}
-function normalizeString(str) {
-    return String.raw `${str}`;
+exports.getPrinter = getPrinter;
+exports.getPrinterDriverOptions = getPrinterDriverOptions;
+exports.getSelectedPaperSize = getSelectedPaperSize;
+exports.getDefaultPrinterName = getDefaultPrinterName;
+exports.printDirect = printDirect;
+exports.printFile = printFile;
+exports.getSupportedPrintFormats = getSupportedPrintFormats;
+exports.getJob = getJob;
+exports.setJob = setJob;
+exports.getSupportedJobCommands = getSupportedJobCommands;
+exports.printDirectAsync = printDirectAsync;
+exports.printFileAsync = printFileAsync;
+exports.getJobAsync = getJobAsync;
+exports.getPrintersAsync = getPrintersAsync;
+exports.getPrinterAsync = getPrinterAsync;
+const path_1 = __importDefault(require("path"));
+const native = require(path_1.default.join(__dirname, '../build/Release/electron_printer.node'));
+/* ===========================
+   DIRECT NATIVE EXPORTS
+=========================== */
+function getPrinters() {
+    return native.getPrinters();
+}
+function getPrinter(printerName) {
+    return native.getPrinter(printerName);
+}
+function getPrinterDriverOptions(printerName) {
+    return native.getPrinterDriverOptions(printerName);
+}
+function getSelectedPaperSize(printerName) {
+    return native.getSelectedPaperSize(printerName);
+}
+function getDefaultPrinterName() {
+    return native.getDefaultPrinterName();
+}
+function printDirect(options) {
+    native.printDirect(options);
+}
+function printFile(options) {
+    native.printFile(options);
+}
+function getSupportedPrintFormats() {
+    return native.getSupportedPrintFormats();
+}
+function getJob(printerName, jobId) {
+    return native.getJob(printerName, jobId);
+}
+function setJob(printerName, jobId, command) {
+    native.setJob(printerName, jobId, command);
+}
+function getSupportedJobCommands() {
+    return native.getSupportedJobCommands();
+}
+/* ==================================================
+   PROMISE WRAPPERS (Async/Await Friendly)
+================================================== */
+function printDirectAsync(options) {
+    return new Promise((resolve, reject) => {
+        native.printDirect({
+            ...options,
+            success: (jobId) => resolve(jobId),
+            error: (err) => reject(err)
+        });
+    });
+}
+function printFileAsync(options) {
+    return new Promise((resolve, reject) => {
+        native.printFile({
+            ...options,
+            success: (jobId) => resolve(jobId),
+            error: (err) => reject(err)
+        });
+    });
+}
+function getJobAsync(printerName, jobId) {
+    return Promise.resolve(native.getJob(printerName, jobId));
+}
+function getPrintersAsync() {
+    return Promise.resolve(native.getPrinters());
+}
+function getPrinterAsync(printerName) {
+    return Promise.resolve(native.getPrinter(printerName));
 }