@plevands/epson-thermal-printer 0.1.2 → 0.2.0

package/README.md

@@ -77,7 +77,7 @@ configurePdfWorker('/assets/pdf.worker.min.mjs');
 import { useEpsonPrinter, usePrinterConfig } from '@plevands/epson-thermal-printer';
 
 function MyPrintComponent() {
-  const { config } = usePrinterConfig();
+  const { config, isConfigured } = usePrinterConfig();
   const { print, isLoading, error } = useEpsonPrinter(config);
 
   const handlePrint = async () => {
@@ -93,7 +93,8 @@ function MyPrintComponent() {
 
   return (
     <div>
-      <button onClick={handlePrint} disabled={isLoading}>
+      {!isConfigured && <p>Please configure the printer first</p>}
+      <button onClick={handlePrint} disabled={isLoading || !isConfigured}>
         {isLoading ? 'Printing...' : 'Print'}
       </button>
       {error && <p>Error: {error}</p>}
@@ -102,6 +103,41 @@ function MyPrintComponent() {
 }
 ```
 
+### Text-Only Printing with Builder (Hooks API)
+
+```typescript
+import { useEpsonPrinter, usePrinterConfig } from '@plevands/epson-thermal-printer';
+
+function TextReceipt() {
+  const { config, isConfigured } = usePrinterConfig({
+    initialConfig: { printerIP: '192.168.1.100' },
+  });
+  const { printWithBuilder, isLoading, error } = useEpsonPrinter(config, { align: 'left' });
+
+  const handlePrintText = async () => {
+    const result = await printWithBuilder((builder) => {
+      builder.addTextAlign('left');
+      builder.addText('TICKET #123\n');
+      builder.addText('Producto A x1     10.00\n');
+      builder.addText('TOTAL             10.00\n');
+      builder.addFeedLine(2);
+      builder.addCut('feed');
+    });
+
+    if (!result.success) {
+      console.error(result.message);
+    }
+  };
+
+  return (
+    <button onClick={handlePrintText} disabled={isLoading || !isConfigured}>
+      Imprimir texto
+      {error ? ` (${error})` : ''}
+    </button>
+  );
+}
+```
+
 ### Service API (No React)
 
 ```typescript
@@ -135,16 +171,21 @@ import { useEpsonPrinter, usePrinterConfig } from '@plevands/epson-thermal-print
 import { useEffect, useState } from 'react';
 
 function PrinterPanel() {
-  const { config } = usePrinterConfig();
+  const { config, isConfigured } = usePrinterConfig();
   const { checkConnection, print, isLoading, error } = useEpsonPrinter(config);
   const [isOnline, setIsOnline] = useState<boolean | null>(null);
 
   // Check connection when component mounts or config changes
   useEffect(() => {
+    if (!isConfigured) return;
     checkConnection().then(result => {
       setIsOnline(result.success);
     });
-  }, [checkConnection]);
+  }, [checkConnection, isConfigured]);
+
+  if (!isConfigured) {
+    return <span>⚙️ Please configure the printer</span>;
+  }
 
   if (isOnline === null) {
     return <span>Checking printer connection...</span>;
@@ -205,7 +246,7 @@ import {
 } from '@plevands/epson-thermal-printer';
 
 function PdfPrinter() {
-  const { config } = usePrinterConfig();
+  const { config, isConfigured } = usePrinterConfig();
   const { processFile } = usePdfProcessor({
     enabled: true,
     trimMargins: { top: 10, bottom: 10, left: 5, right: 5 },
@@ -287,23 +328,51 @@ interface EpsonPrinterConfig {
 
 Main hook for printer operations with automatic SDK loading.
 
+**Parameters:**
+- `config` - `EpsonPrinterConfig | null` — printer configuration (pass `null` or unconfigured hook value; operations will return `NOT_CONFIGURED` error)
+- `options?` - `PrintOptions` — default print options
+
 **Returns:**
 - `print(canvas)` - Print a single canvas
 - `printPages(canvases, options?)` - Print multiple pages
+- `printWithBuilder(builder => ...)` - Print custom ePOSBuilder commands (ideal for text receipts)
+- `checkConnection()` - Check printer connection without printing
 - `testConnection()` - Test printer connection
 - `isLoading` - Loading state
 - `error` - Error message if any
 - `sdkStatus` - SDK loading status
 
-#### `usePrinterConfig()`
+#### `usePrinterConfig(options?)`
 
 Manages printer configuration with localStorage persistence.
 
+Without arguments, `config` starts as `null` until the user calls `updateConfig`. Pass `initialConfig` to provide defaults for new users. Pass `storageKey` to use a custom localStorage key — useful when managing multiple printer configurations (e.g. one per network).
+
+**Options (`UsePrinterConfigOptions`):**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `initialConfig` | `EpsonPrinterConfig` | `undefined` | Defaults for new users. localStorage values take priority for returning users. |
+| `storageKey` | `string` | `'epson-printer-config'` | localStorage key for this configuration instance. |
+
+```typescript
+// No defaults — config is null until user configures
+const { config, isConfigured } = usePrinterConfig();
+
+// With defaults — config starts pre-filled
+const { config, isConfigured } = usePrinterConfig({
+  initialConfig: { printerIP: '10.0.0.50' },
+});
+
+// Multiple configs for different networks
+const office    = usePrinterConfig({ storageKey: 'printer-office' });
+const warehouse = usePrinterConfig({ storageKey: 'printer-warehouse' });
+```
+
 **Returns:**
-- `config` - Current configuration
-- `updateConfig(partial)` - Update configuration
-- `resetConfig()` - Reset to defaults
-- `isConfigured` - Boolean
+- `config` - Current configuration (`EpsonPrinterConfig | null`)
+- `updateConfig(partial)` - Update configuration (persists to localStorage)
+- `resetConfig()` - Reset to initial value (`initialConfig` if provided, otherwise `null`) and clear localStorage
+- `isConfigured` - `true` when config is not null and has a valid printer IP
 
 #### `usePdfProcessor(config?)`
 

package/dist/hooks/useEpsonPrinter.d.ts

@@ -1,2 +1,2 @@
 import { EpsonPrinterConfig, PrintOptions, UseEpsonPrinterReturn } from '../types';
-export declare function useEpsonPrinter(config: EpsonPrinterConfig, options?: PrintOptions): UseEpsonPrinterReturn;
+export declare function useEpsonPrinter(config: EpsonPrinterConfig | null, options?: PrintOptions): UseEpsonPrinterReturn;

package/dist/hooks/usePrinterConfig.d.ts

@@ -1,2 +1,2 @@
-import { UsePrinterConfigReturn } from '../types';
-export declare function usePrinterConfig(): UsePrinterConfigReturn;
+import { UsePrinterConfigOptions, UsePrinterConfigReturn } from '../types';
+export declare function usePrinterConfig(options?: UsePrinterConfigOptions): UsePrinterConfigReturn;