enhanced-printer 1.0.4 → 1.0.6

package/README.md

@@ -18,9 +18,6 @@ A powerful Node.js/Electron library for advanced PDF printing with job tracking,
 npm install enhanced-printer
 ```
 
-> **Note**: Replace `enhanced-printer` with the actual package name you choose when publishing to npm.
-> Check `PUBLISH-CHECKLIST.md` for publishing steps.
-
 ## Requirements
 
 - **Node.js**: 20.0.0 or higher
@@ -40,11 +37,13 @@ async function printPDF() {
   // Print with default settings
   const result = await print({
     printerName: 'Your Printer Name',
-    filePath: 'C:\\path\\to\\document.pdf'
+    filePath: 'C:\\path\\to\\document.pdf',
+    jobName: 'MyJob_001'
   });
   
   console.log('Success:', result.success);
   console.log('Job ID:', result.jobId);
+  console.log('Job Name:', result.jobName);
 }
 
 printPDF();
@@ -52,13 +51,14 @@ printPDF();
 
 ## Available Methods
 
-- `print()` - Print PDF with custom settings
-- `getPrinters()` - Get list of available printers
-- `getDefaultPrinter()` - Get default printer name
-- `getJobs()` - Get all print jobs with custom names
-- `getPrinterJobs()` - Get all print jobs (alias for getJobs)
-- `getJobStatus()` - Get status of specific job by ID
-- `cancelJob()` - Cancel a print job
+| Method | Description |
+|--------|-------------|
+| `print()` | Print a PDF with custom settings |
+| `getPrinters()` | Get list of available printers |
+| `getDefaultPrinter()` | Get default printer name |
+| `getJobInfo()` | Get info of a specific job by custom job name |
+| `getJobs()` | Get all print jobs for a printer |
+| `cancelJob()` | Cancel a print job by custom job name |
 
 ## API Reference
 
@@ -76,7 +76,7 @@ interface PrintOptions {
   // Optional settings - defaults to printer preferences if not specified
   pageSize?: string;       // e.g., "A4", "A5", "A6", "Letter", "Legal"
   tray?: string | number;  // Tray name or number
-  jobName?: string;        // Document/job name for tracking
+  jobName?: string;        // Custom job name for tracking (auto-generated if not provided)
   copies?: number;         // Number of copies
   orientation?: 'portrait' | 'landscape';
   duplex?: 'simplex' | 'duplex';
@@ -92,7 +92,7 @@ interface PrintOptions {
 interface PrintResult {
   success: boolean;
   jobId?: number;        // Job ID from print spooler (if available)
-  jobName: string;       // Document name used for tracking
+  jobName: string;       // Custom job name used for tracking
   error?: string;        // Error message if print failed
 }
 ```
@@ -105,10 +105,13 @@ const result = await print({
   filePath: './invoice.pdf',
   pageSize: 'A4',
   tray: 2,
-  copies: 2
+  copies: 2,
+  jobName: 'Invoice_12345'
 });
 ```
 
+---
+
 ### `getPrinters(): Promise<PrinterInfo[]>`
 
 Gets a list of available printers.
@@ -132,29 +135,80 @@ printers.forEach(p => {
 });
 ```
 
+---
+
 ### `getDefaultPrinter(): Promise<string | null>`
 
 Gets the name of the default printer.
 
-### `getJobStatus(printerName: string, jobId: number): Promise<JobInfo | null>`
+**Example:**
+
+```javascript
+const defaultPrinter = await getDefaultPrinter();
+console.log('Default printer:', defaultPrinter);
+```
+
+---
+
+### `getJobInfo(customJobName: string, printerName?: string): Promise<JobInfo | null>`
+
+Gets detailed information about a specific print job using the custom job name provided during printing.
+
+**Returns:**
+
+```typescript
+interface JobInfo {
+  jobId: number;
+  jobName: string;          // Document name from Windows
+  customJobName: string;    // Custom job name provided during print
+  printerName: string;
+  status: string[];         // List of status flags, e.g. ["PRINTING", "RETAINED"]
+  pages: number;
+  size?: number;            // Size in bytes
+  userName?: string;
+  submittedTime?: string;
+}
+```
 
-Gets information about a specific print job.
+**Possible status values:** `PAUSED`, `ERROR`, `DELETING`, `SPOOLING`, `PRINTING`, `OFFLINE`, `PAPER_OUT`, `PRINTED`, `DELETED`, `BLOCKED_DEVICE_QUEUE`, `USER_INTERVENTION`, `RESTART`, `COMPLETE`, `RETAINED`, `RENDERING_LOCALLY`
 
 **Example:**
 
 ```javascript
-const jobInfo = await getJobStatus('HP LaserJet', 123);
-console.log('Status:', jobInfo.status);
+const jobInfo = await getJobInfo('Invoice_12345');
+console.log('Status:', jobInfo.status);   // ["PRINTING", "RETAINED"]
 console.log('Pages:', jobInfo.pages);
 ```
 
-### `getPrinterJobs(printerName: string): Promise<JobInfo[]>`
+---
+
+### `getJobs(printerName: string): Promise<JobInfo[]>`
 
 Gets all print jobs for a specific printer.
 
-### `cancelJob(printerName: string, jobId: number): Promise<boolean>`
+**Example:**
+
+```javascript
+const jobs = await getJobs('HP LaserJet');
+jobs.forEach(job => {
+  console.log(`Job ${job.jobId} (${job.customJobName}): ${job.status.join(', ')}`);
+});
+```
+
+---
+
+### `cancelJob(customJobName: string, printerName?: string): Promise<boolean>`
 
-Cancels a print job.
+Cancels a print job using the custom job name.
+
+**Example:**
+
+```javascript
+const cancelled = await cancelJob('Invoice_12345');
+console.log('Cancelled:', cancelled);
+```
+
+---
 
 ## Usage Examples
 
@@ -163,7 +217,6 @@ Cancels a print job.
 When you don't specify optional settings, the library automatically uses the printer's default configuration:
 
 ```javascript
-// Uses printer's default page size, tray, and other settings
 const result = await print({
   printerName: 'My Printer',
   filePath: './document.pdf'
@@ -173,27 +226,14 @@ const result = await print({
 ### Custom Page Size with Default Tray
 
 ```javascript
-// Custom page size, but uses printer's default tray
 const result = await print({
   printerName: 'Label Printer',
   filePath: './label.pdf',
-  pageSize: 'A6'  // 4x6 inches for labels
+  pageSize: 'A6'
   // tray not specified - uses default
 });
 ```
 
-### Custom Tray with Default Page Size
-
-```javascript
-// Specific tray, but uses printer's default page size
-const result = await print({
-  printerName: 'Office Printer',
-  filePath: './document.pdf',
-  tray: 'Tray 2'  // or use number: tray: 2
-  // pageSize not specified - uses default
-});
-```
-
 ### Multiple Custom Settings
 
 ```javascript
@@ -215,28 +255,31 @@ const result = await print({
 ```javascript
 const result = await print({
   printerName: 'My Printer',
-  filePath: './document.pdf'
+  filePath: './document.pdf',
+  jobName: 'MyJob_001'
 });
 
-if (result.jobId) {
-  // Monitor job status
-  const jobInfo = await getJobStatus('My Printer', result.jobId);
-  console.log(`Job ${jobInfo.jobId}: ${jobInfo.status}`);
+if (result.success) {
+  // Get job info using custom job name
+  const jobInfo = await getJobInfo('MyJob_001');
+  console.log(`Job ${jobInfo.jobId}: ${jobInfo.status.join(', ')}`);
+  
+  // Get all jobs for the printer
+  const allJobs = await getJobs('My Printer');
+  console.log(`Total jobs in queue: ${allJobs.length}`);
   
   // Cancel if needed
-  // await cancelJob('My Printer', result.jobId);
+  // await cancelJob('MyJob_001');
 }
 ```
 
 ## Electron Integration
 
-See `examples/electron-integration.js` for a complete example.
-
 **Main Process:**
 
 ```javascript
 const { ipcMain } = require('electron');
-const { print, getPrinters } = require('@your-org/enhanced-printer');
+const { print, getPrinters, getJobs } = require('enhanced-printer');
 
 ipcMain.handle('print-pdf', async (event, options) => {
   return await print(options);
@@ -245,6 +288,10 @@ ipcMain.handle('print-pdf', async (event, options) => {
 ipcMain.handle('get-printers', async () => {
   return await getPrinters();
 });
+
+ipcMain.handle('get-jobs', async (event, printerName) => {
+  return await getJobs(printerName);
+});
 ```
 
 **Renderer Process:**
@@ -252,7 +299,8 @@ ipcMain.handle('get-printers', async () => {
 ```javascript
 const result = await window.printerAPI.print({
   printerName: 'My Printer',
-  filePath: pdfPath
+  filePath: pdfPath,
+  jobName: 'MyJob_001'
 });
 ```
 
@@ -261,12 +309,13 @@ const result = await window.printerAPI.print({
 This library is written in TypeScript and includes full type definitions.
 
 ```typescript
-import { print, PrintOptions, PrintResult } from '@your-org/enhanced-printer';
+import { print, PrintOptions, PrintResult, JobInfo } from 'enhanced-printer';
 
 const options: PrintOptions = {
   printerName: 'My Printer',
   filePath: './document.pdf',
-  pageSize: 'A4'
+  pageSize: 'A4',
+  jobName: 'TypedJob_001'
 };
 
 const result: PrintResult = await print(options);
@@ -276,7 +325,9 @@ const result: PrintResult = await print(options);
 
 1. **PDF Printing**: Uses `pdf-to-printer` library which wraps SumatraPDF on Windows
 2. **Job ID Retrieval**: Queries Windows print spooler using PowerShell commands
-3. **Default Settings**: When settings aren't specified, SumatraPDF uses the printer's DEVMODE defaults
+3. **Custom Job Names**: Maps user-provided job names to system job IDs for easy tracking
+4. **Status Decoding**: Converts numeric Windows job status bitmask into human-readable status flags
+5. **Default Settings**: When settings aren't specified, SumatraPDF uses the printer's DEVMODE defaults
 
 ## Limitations
 
@@ -284,15 +335,6 @@ const result: PrintResult = await print(options);
 - **PDF Files**: Designed for PDF printing (for raw data, convert to PDF first)
 - **Job ID Timing**: Very fast printers may complete jobs before ID can be retrieved
 
-## Examples
-
-See the `examples/` directory for complete working examples:
-
-- `basic-print.js` - Simple printing with defaults
-- `custom-settings.js` - Custom page sizes, trays, and options
-- `job-monitoring.js` - Job status tracking
-- `electron-integration.js` - Electron app integration
-
 ## Troubleshooting
 
 ### Job ID is undefined

package/lib/job-tracker.js

@@ -6,6 +6,48 @@ exports.getJobInfo = getJobInfo;
 exports.getAllJobs = getAllJobs;
 const child_process_1 = require("child_process");
 const job_name_mapper_1 = require("./job-name-mapper");
+/**
+ * Windows print job status flags (bitmask values)
+ * See: https://learn.microsoft.com/en-us/windows/win32/printdocs/job-info-2
+ */
+const JOB_STATUS_FLAGS = {
+    0x0001: 'PAUSED',
+    0x0002: 'ERROR',
+    0x0004: 'DELETING',
+    0x0008: 'SPOOLING',
+    0x0010: 'PRINTING',
+    0x0020: 'OFFLINE',
+    0x0040: 'PAPER_OUT',
+    0x0080: 'PRINTED',
+    0x0100: 'DELETED',
+    0x0200: 'BLOCKED_DEVICE_QUEUE',
+    0x0400: 'USER_INTERVENTION',
+    0x0800: 'RESTART',
+    0x1000: 'COMPLETE',
+    0x2000: 'RETAINED',
+    0x4000: 'RENDERING_LOCALLY',
+};
+/**
+ * Decodes a numeric job status bitmask into a list of status strings.
+ * e.g. 8210 (0x2012) => ["Error", "Printing", "Retained"]
+ */
+function decodeJobStatus(status) {
+    // If it's already a string, return it as a single-element array
+    if (typeof status === 'string') {
+        return status ? [status] : ['Unknown'];
+    }
+    const numericStatus = Number(status);
+    if (isNaN(numericStatus) || numericStatus === 0) {
+        return ['None'];
+    }
+    const flags = [];
+    for (const [bit, name] of Object.entries(JOB_STATUS_FLAGS)) {
+        if (numericStatus & Number(bit)) {
+            flags.push(name);
+        }
+    }
+    return flags.length > 0 ? flags : ['Unknown'];
+}
 /**
  * Retrieves job ID by document name using PowerShell
  */
@@ -45,7 +87,7 @@ async function getJobInfoBySystemId(printerName, jobId) {
             jobName: result.DocumentName || '',
             customJobName: customName || result.DocumentName || '',
             printerName: printerName,
-            status: result.JobStatus || 'Unknown',
+            status: decodeJobStatus(result.JobStatus),
             pages: result.TotalPages || 0,
             size: result.Size,
             userName: result.UserName,
@@ -90,7 +132,7 @@ async function getAllJobs(printerName) {
                 jobName: job.DocumentName || '',
                 customJobName: customName || job.DocumentName || '', // Use custom name if available
                 printerName: printerName,
-                status: job.JobStatus || 'Unknown',
+                status: decodeJobStatus(job.JobStatus),
                 pages: job.TotalPages || 0,
                 size: job.Size,
                 userName: job.UserName,

package/lib/types.d.ts

@@ -68,8 +68,8 @@ export interface JobInfo {
     customJobName: string;
     /** Name of the printer */
     printerName: string;
-    /** Current status of the job */
-    status: string;
+    /** Current status of the job (list of active status flags) */
+    status: string[];
     /** Number of pages */
     pages: number;
     /** Size in bytes */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enhanced-printer",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Advanced PDF printing library with job tracking, custom page sizes, and tray selection for Node.js and Electron",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",