@tecsom/apipos-js 0.0.0-stage → 2.0.4

package/dist/printer.js

@@ -0,0 +1,189 @@
+/*
+ * Impresora de Apipos: manda trabajos RAW (ticket ESC/POS o renderizado a PDF
+ * en Apipos) y PDF a UNA impresora por su nombre exacto, abre su cajón y pide
+ * la vista previa con sus settings. Se crea con `apipos.createPrinter(name, settings)`.
+ *
+ * No depende de la app que la usa: lo que haya que hacerle al texto antes de
+ * imprimir lo decide el `transformContent` del `Apipos` que la creó.
+ */
+import { isRecord, isUnknownArray, unexpectedResponse } from './http.js';
+// Settings sin los que no se puede armar un ticket, con el tipo que exige Apipos.
+const REQUIRED_SETTINGS = [['paper_size', 'number']];
+function isOptional(value, type) {
+    return value === undefined || typeof value === type;
+}
+// La forma de `data` cambia con el tipo de trabajo (ver PrintResult); se exige lo
+// común (`printer`) y que lo demás, si viene, tenga el tipo del contrato.
+function isPrintResult(value) {
+    return (isRecord(value) &&
+        typeof value.printer === 'string' &&
+        isOptional(value.type, 'string') &&
+        isOptional(value.char_width, 'number') &&
+        isOptional(value.strategy, 'string') &&
+        isOptional(value.width_dots, 'number') &&
+        isOptional(value.cut, 'boolean') &&
+        (value.media === undefined || value.media === null || typeof value.media === 'string') &&
+        isOptional(value.renderer, 'string') &&
+        (value.page_mm === undefined || isRecord(value.page_mm)) &&
+        (value.fonts === undefined || isUnknownArray(value.fonts)) &&
+        (value.warnings === undefined || isUnknownArray(value.warnings)) &&
+        isOptional(value.drawer_opened, 'boolean'));
+}
+function isOpenDrawerResult(value) {
+    return isRecord(value) && typeof value.printer === 'string';
+}
+/**
+ * Única fuente de verdad del mapeo `options` (camelCase, de la librería) →
+ * claves de `settings` (snake_case, del cable). La usan `print()` y `render()`.
+ * Solo se copian las opciones definidas (`undefined` no viaja; `false` y `0`
+ * sí) y `options.settings` va al final: gana sobre las de arriba.
+ */
+function settingsFromOptions(options) {
+    const { renderer, pdfMode, font, marginsMm, widthMm, maxHeightMm, cut, settings } = options;
+    const mapped = {};
+    if (renderer !== undefined)
+        mapped.renderer = renderer;
+    if (pdfMode !== undefined)
+        mapped.pdf_mode = pdfMode;
+    if (font !== undefined)
+        mapped.font = font;
+    if (marginsMm !== undefined)
+        mapped.margins_mm = marginsMm;
+    if (widthMm !== undefined)
+        mapped.width_mm = widthMm;
+    if (maxHeightMm !== undefined)
+        mapped.max_height_mm = maxHeightMm;
+    if (cut !== undefined)
+        mapped.cut = cut;
+    if (settings !== undefined) {
+        for (const [key, value] of Object.entries(settings)) {
+            if (value !== undefined)
+                mapped[key] = value;
+        }
+    }
+    return mapped;
+}
+export class ApiPosPrinter {
+    #name;
+    #apipos;
+    settings;
+    /**
+     * Valida `settings.paper_size` (number, obligatorio): lanza
+     * `Missing required setting: paper_size` o
+     * `Invalid type for setting paper_size: expected number, got <tipo>`.
+     */
+    constructor(name, settings = {}, apipos) {
+        this.#name = name;
+        this.settings = settings;
+        this.#apipos = apipos;
+        this.validateSettings();
+    }
+    validateSettings() {
+        for (const [key, type] of REQUIRED_SETTINGS) {
+            const value = this.settings[key];
+            if (value === undefined) {
+                throw new Error(`Missing required setting: ${key}`);
+            }
+            if (typeof value !== type) {
+                throw new Error(`Invalid type for setting ${key}: expected ${type}, got ${typeof value}`);
+            }
+        }
+    }
+    get name() {
+        return this.#name;
+    }
+    get apiUrl() {
+        return this.#apipos.apiUrl;
+    }
+    // Único punto de envío a POST /print. Maneja la respuesta estandarizada
+    // de Apipos: { status, data, message }. Devuelve `data` o lanza con `message`.
+    async #send(payload) {
+        const data = await this.#apipos.request('POST', '/print', { body: { printer: this.#name, ...payload } });
+        if (data !== null && !isPrintResult(data))
+            throw unexpectedResponse('/print');
+        return data;
+    }
+    /**
+     * Trabajo RAW: `content` es la lista de elementos del ticket.
+     *
+     * Lo que haya que hacerle al texto (p. ej. una limpieza base o un
+     * interruptor por dispositivo "sin acentos ni ñ") lo aplica el
+     * `transformContent` del cliente en CADA trabajo, no al crear la impresora:
+     * así un cambio de ajustes vale desde el siguiente ticket sin recargar.
+     *
+     * SIN `options` (o con `{}`) el payload es el de v1, byte a byte:
+     * `{ printer, type: 'RAW', settings: this.settings, content }`.
+     *
+     * Con `options` se agregan claves SOLO dentro de `settings` (nunca al nivel
+     * raíz) y `this.settings` no se modifica:
+     *   renderer → renderer ('escpos' | 'pdf'; con 'pdf' Apipos maqueta el ticket
+     *     como PDF con fuentes del sistema y lo imprime por la ruta PDF)
+     *   pdfMode → pdf_mode ; font → font ({ family, size, line_height })
+     *   marginsMm → margins_mm ; widthMm → width_mm ; maxHeightMm → max_height_mm
+     *   cut → cut ; settings → se mezcla al final y gana (claves nuevas del backend)
+     * Las opciones `undefined` no viajan.
+     */
+    async print(content, options = {}) {
+        const printable = this.#apipos.applyTransform(content);
+        const overrides = settingsFromOptions(options);
+        // Sin opciones definidas viaja `this.settings` MISMO (no una copia): el
+        // payload de v1 sale byte a byte igual. Con opciones, un objeto nuevo.
+        const settings = Object.keys(overrides).length === 0 ? this.settings : { ...this.settings, ...overrides };
+        return this.#send({ type: 'RAW', settings, content: printable });
+    }
+    /**
+     * Abre el cajón de dinero conectado a ESTA impresora, sin imprimir nada.
+     * POST /open-withdrawer con `{ printer }` → `{ printer }`. Lanza
+     * `ApiposError` si Apipos responde error (p. ej. `Printer 'X' not found.`).
+     */
+    async openDrawer() {
+        const data = await this.#apipos.request('POST', '/open-withdrawer', { body: { printer: this.#name } });
+        if (!isOpenDrawerResult(data))
+            throw unexpectedResponse('/open-withdrawer');
+        return data;
+    }
+    /**
+     * Vista previa con los settings de ESTA impresora y las mismas `options` que
+     * `print()`, con el mismo mapeo a `settings`:
+     * `apipos.renderTicket(content, { settings: { ...this.settings, ...mapeo(options) }, format, dpi })`.
+     * No imprime ni valida la impresora; `this.settings` no se modifica. Default
+     * `png` a 203 dpi (la resolución de una tiquetera: 72 mm → 576 px de ancho).
+     */
+    async render(content, { format = 'png', dpi = 203, ...options } = {}) {
+        const settings = { ...this.settings, ...settingsFromOptions(options) };
+        return this.#apipos.renderTicket(content, { settings, format, dpi });
+    }
+    /**
+     * Trabajo PDF: en el navegador el PDF es un Blob; se envía en base64.
+     * Opciones:
+     *   pdfMode: 'driver' (el driver de la impresora renderiza el PDF — el modo
+     *     correcto para etiquetas, ej. AiYin) | 'raw' (rasteriza a ESC/POS, para
+     *     tiqueteras de recibos). Default del servidor: 'driver' si se mandan
+     *     labelSettings, 'raw' si no.
+     *   labelSettings: { width, height, unit: 'mm'|'inch' } — tamaño de la
+     *     etiqueta; la página del PDF debe medir lo mismo.
+     */
+    async printPDF(blob, { pdfMode, labelSettings } = {}) {
+        const data = await blobToBase64(blob);
+        const settings = { ...this.settings };
+        if (pdfMode)
+            settings.pdf_mode = pdfMode;
+        if (labelSettings)
+            settings.label_settings = labelSettings;
+        return this.#send({ type: 'PDF', settings, data });
+    }
+}
+// Bytes por llamada a `String.fromCharCode`: pasarle un PDF entero como
+// argumentos revienta la pila; 32 KiB está muy por debajo del límite de los motores.
+const BASE64_CHUNK = 0x8000;
+// Mismo base64 que daba `FileReader.readAsDataURL` (sin el prefijo
+// "data:<mime>;base64,"), pero sin FileReader: `arrayBuffer()` + `btoa` existen
+// en el navegador y en Node, así que se puede probar fuera del navegador.
+async function blobToBase64(blob) {
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    let binary = '';
+    for (let offset = 0; offset < bytes.length; offset += BASE64_CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_CHUNK));
+    }
+    return btoa(binary);
+}

package/dist/strip-accents.d.ts

@@ -0,0 +1,21 @@
+import type { TicketContent } from './types.js';
+/**
+ * Devuelve `text` sin acentos ni ñ. Cada vocal acentuada y cada ñ cambian un
+ * carácter por otro, así que el ancho de las líneas y la alineación de las
+ * columnas del ticket no se mueven; sólo `¿` y `¡` acortan la línea en uno.
+ * Lo que no es string se devuelve tal cual.
+ */
+export declare function stripAccents(text: string): string;
+export declare function stripAccents<T>(text: T): T;
+/**
+ * Aplica `stripAccents` a todo el texto de un trabajo RAW de Apipos.
+ *
+ * Devuelve un arreglo NUEVO y no toca la entrada: quien imprime puede reusar
+ * su contenido (otra copia, o el reintento sin logo). Recorre los strings a
+ * cualquier profundidad (`text.data`, `special_text.data.text1/text2`,
+ * `table.data.rows`), pero deja intactos los elementos `image`: su `data` es
+ * base64, no puede llevar acentos, y normalizar cientos de KB en cada ticket
+ * sería trabajo tirado.
+ */
+export declare function stripAccentsFromContent(content: TicketContent): TicketContent;
+export declare function stripAccentsFromContent<T>(content: T): T;

package/dist/strip-accents.js

@@ -0,0 +1,57 @@
+/*
+ * Texto de impresión sin acentos ni ñ, para las tiqueteras que no traen la
+ * tabla Latin-1.
+ *
+ * Apipos manda cada carácter como su byte Latin-1 y nunca elige página de
+ * códigos; una impresora que arranca en otra página (las genéricas suelen
+ * arrancar en CP437) pinta otro glifo por cada byte ≥ 0x80: la `ñ` sale `±`,
+ * la `í` sale `φ`, la `á` sale `ß`. Con el texto reducido a letras base no queda
+ * byte que la impresora pueda malinterpretar.
+ *
+ * Módulo puro (sin DOM ni imports en runtime: solo un tipo) para poder probarlo
+ * directamente desde mocha. Quién decide si se aplica es el `transformContent`
+ * del cliente.
+ */
+// Marcas combinantes que deja `normalize('NFD')` al separar la letra base de su
+// acento, diéresis, virgulilla o cedilla. Quitarlas cubre cualquier letra con
+// diacrítico sin tener que listarlas una por una.
+const COMBINING_MARKS = /[\u0300-\u036f]/g;
+// Lo que NFD no descompone. Los signos de apertura se quitan (la tiquetera
+// tampoco los tiene y el de cierre basta para leer la frase) y los ordinales
+// se vuelven su letra.
+const EXPLICIT_REPLACEMENTS = { '¿': '', '¡': '', ª: 'a', º: 'o' };
+const EXPLICIT_PATTERN = /[¿¡ªº]/g;
+export function stripAccents(text) {
+    if (typeof text !== 'string')
+        return text;
+    return text
+        .normalize('NFD')
+        .replace(COMBINING_MARKS, '')
+        .replace(EXPLICIT_PATTERN, char => EXPLICIT_REPLACEMENTS[char] ?? char);
+}
+export function stripAccentsFromContent(content) {
+    if (!isUnknownArray(content))
+        return stripStrings(content);
+    return content.map(item => (isRecord(item) && item.type === 'image' ? item : stripStrings(item)));
+}
+function stripStrings(value) {
+    if (typeof value === 'string')
+        return stripAccents(value);
+    if (isUnknownArray(value))
+        return value.map(stripStrings);
+    if (isRecord(value)) {
+        const stripped = {};
+        for (const key in value) {
+            stripped[key] = stripStrings(value[key]);
+        }
+        return stripped;
+    }
+    return value;
+}
+// Guardas locales (el módulo se mantiene sin imports de código).
+function isUnknownArray(value) {
+    return Array.isArray(value);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/ticket-preview.d.ts

@@ -0,0 +1,33 @@
+import type { Apipos } from './apipos.js';
+import type { RenderPreviewOptions, TicketContent, TicketItem } from './types.js';
+/** Columnas de texto del papel (fuente A de la impresora térmica). */
+export declare function ticketColumns(paperSize?: number): number;
+/** Estilos del ticket. Papel blanco y tinta negra también en modo oscuro. */
+export declare const TICKET_PREVIEW_CSS = "\n.tkt { --tkt-cols: 48; box-sizing: content-box; width: calc(var(--tkt-cols) * 1ch); max-width: 100%;\n    margin: 0 auto; padding: 14px 12px 18px; background: #fff; color: #111;\n    font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;\n    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.18); border-radius: 2px; }\n.tkt__text { white-space: pre-wrap; overflow-wrap: anywhere; }\n.tkt__text--big { font-size: 1.2em; font-weight: 700; }\n.tkt__row { display: flex; justify-content: space-between; gap: 1ch; }\n.tkt__row > span:first-child { flex: 1 1 auto; white-space: pre-wrap; overflow-wrap: anywhere; }\n.tkt__row > span:last-child { flex: 0 0 auto; white-space: nowrap; text-align: right; }\n.tkt__sep { white-space: nowrap; overflow: hidden; color: #444; }\n@media print { .tkt { box-shadow: none; padding: 0; } }\n";
+/**
+ * HTML del ticket a partir del contenido de Apipos.
+ * @param content  Lo que recibe `printer.print(content)`.
+ */
+export declare function renderTicketHtml(content: readonly TicketItem[] | null | undefined, { paperSize }?: {
+    paperSize?: number;
+}): string;
+/**
+ * Imprime el ticket desde el navegador (PDF o impresora del sistema) sin sacar
+ * el resto de la página: lo pinta en un iframe oculto y lo imprime solo.
+ */
+export declare function printTicketHtml(html: string, { title }?: {
+    title?: string;
+}): void;
+/**
+ * Vista previa REAL (la pinta Apipos con el mismo motor que imprime). Devuelve un
+ * data URL `data:image/png;base64,...` listo para un <img>. Para el camino ESC/POS
+ * sigue existiendo renderTicketHtml (aproximación en pantalla).
+ *
+ * Usa `apipos.renderTicket(content, { settings, format: 'png', dpi })`, así que
+ * `content` pasa por el `transformContent` del cliente, como al imprimir. Lanza
+ * lo mismo que `renderTicket` (sin conexión, `ApiposError`, respuesta inesperada).
+ *
+ * @param apipos  El cliente (basta con algo que tenga `renderTicket`).
+ * @param options `settings` del ticket (default `{}`) y `dpi` (default 150).
+ */
+export declare function renderTicketPreviewPng(apipos: Pick<Apipos, 'renderTicket'>, content: TicketContent, { settings, dpi }?: RenderPreviewOptions): Promise<string>;

package/dist/ticket-preview.js

@@ -0,0 +1,115 @@
+/* =====================================================================
+   Vista previa en pantalla de un ticket ESC/POS (Apipos).
+
+   Pinta el MISMO arreglo de elementos que se manda a la impresora
+   ({ type: 'text' | 'special_text' | 'separator' }), línea por línea, con el
+   ancho de columnas del papel: 48 en 80 mm, 32 en 58 mm. No arma su propio
+   resumen: si el ticket cambia, la vista previa cambia con él.
+
+   renderTicketPreviewPng() es la vista previa REAL: la pinta Apipos con el
+   mismo renderizador que imprime (POST /render).
+   ===================================================================== */
+const HTML_ESCAPES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;'
+};
+const esc = (value) => String(value ?? '').replace(/[&<>"']/g, c => HTML_ESCAPES[c] ?? c);
+// Lee una propiedad de lo que sea sin fallar: los tickets llegan de código JS
+// sin tipos, y un elemento raro debe pintarse vacío, no romper la vista previa.
+function field(value, key) {
+    return isRecord(value) ? value[key] : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Columnas de texto del papel (fuente A de la impresora térmica). */
+export function ticketColumns(paperSize = 80) {
+    return Number(paperSize) === 58 ? 32 : 48;
+}
+/** Estilos del ticket. Papel blanco y tinta negra también en modo oscuro. */
+export const TICKET_PREVIEW_CSS = `
+.tkt { --tkt-cols: 48; box-sizing: content-box; width: calc(var(--tkt-cols) * 1ch); max-width: 100%;
+    margin: 0 auto; padding: 14px 12px 18px; background: #fff; color: #111;
+    font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.18); border-radius: 2px; }
+.tkt__text { white-space: pre-wrap; overflow-wrap: anywhere; }
+.tkt__text--big { font-size: 1.2em; font-weight: 700; }
+.tkt__row { display: flex; justify-content: space-between; gap: 1ch; }
+.tkt__row > span:first-child { flex: 1 1 auto; white-space: pre-wrap; overflow-wrap: anywhere; }
+.tkt__row > span:last-child { flex: 0 0 auto; white-space: nowrap; text-align: right; }
+.tkt__sep { white-space: nowrap; overflow: hidden; color: #444; }
+@media print { .tkt { box-shadow: none; padding: 0; } }
+`;
+/**
+ * HTML del ticket a partir del contenido de Apipos.
+ * @param content  Lo que recibe `printer.print(content)`.
+ */
+export function renderTicketHtml(content, { paperSize = 80 } = {}) {
+    const cols = ticketColumns(paperSize);
+    const items = content || [];
+    const lines = items.map((item) => {
+        const type = field(item, 'type');
+        if (type === 'separator')
+            return `<div class="tkt__sep">${'-'.repeat(cols)}</div>`;
+        if (type === 'special_text') {
+            const data = field(item, 'data');
+            return `<div class="tkt__row"><span>${esc(field(data, 'text1'))}</span><span>${esc(field(data, 'text2'))}</span></div>`;
+        }
+        const align = field(item, 'align');
+        const textAlign = align === 'center' || align === 'right' ? align : 'left';
+        const fontSize = field(item, 'font_size');
+        const big = fontSize === 'md' || fontSize === 'lg' ? ' tkt__text--big' : '';
+        return `<div class="tkt__text${big}" style="text-align: ${textAlign}">${esc(field(item, 'data'))}</div>`;
+    });
+    return `<div class="tkt" style="--tkt-cols: ${cols}">${lines.join('')}</div>`;
+}
+/**
+ * Imprime el ticket desde el navegador (PDF o impresora del sistema) sin sacar
+ * el resto de la página: lo pinta en un iframe oculto y lo imprime solo.
+ */
+export function printTicketHtml(html, { title = 'Ticket' } = {}) {
+    const frame = document.createElement('iframe');
+    frame.setAttribute('aria-hidden', 'true');
+    frame.style.cssText = 'position: fixed; right: 0; bottom: 0; width: 0; height: 0; border: 0;';
+    document.body.appendChild(frame);
+    const doc = frame.contentDocument;
+    if (doc === null) {
+        frame.remove();
+        throw new Error('No se pudo preparar el iframe para imprimir el ticket.');
+    }
+    doc.open();
+    doc.write(`<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>` +
+        `<style>@page { margin: 8mm; } body { margin: 0; } ${TICKET_PREVIEW_CSS}</style></head>` +
+        `<body>${html}</body></html>`);
+    doc.close();
+    const win = frame.contentWindow;
+    if (win === null) {
+        frame.remove();
+        throw new Error('No se pudo preparar el iframe para imprimir el ticket.');
+    }
+    const cleanup = () => setTimeout(() => frame.remove(), 500);
+    win.addEventListener('afterprint', cleanup);
+    win.focus();
+    win.print();
+    // Safari no siempre dispara afterprint: el iframe se retira igual.
+    setTimeout(cleanup, 60000);
+}
+/**
+ * Vista previa REAL (la pinta Apipos con el mismo motor que imprime). Devuelve un
+ * data URL `data:image/png;base64,...` listo para un <img>. Para el camino ESC/POS
+ * sigue existiendo renderTicketHtml (aproximación en pantalla).
+ *
+ * Usa `apipos.renderTicket(content, { settings, format: 'png', dpi })`, así que
+ * `content` pasa por el `transformContent` del cliente, como al imprimir. Lanza
+ * lo mismo que `renderTicket` (sin conexión, `ApiposError`, respuesta inesperada).
+ *
+ * @param apipos  El cliente (basta con algo que tenga `renderTicket`).
+ * @param options `settings` del ticket (default `{}`) y `dpi` (default 150).
+ */
+export async function renderTicketPreviewPng(apipos, content, { settings = {}, dpi = 150 } = {}) {
+    const { base64 } = await apipos.renderTicket(content, { settings, format: 'png', dpi });
+    return `data:image/png;base64,${base64}`;
+}