@tecsom/apipos-js 0.0.0-stage → 2.0.3

package/dist/apipos.js

@@ -0,0 +1,291 @@
+/*
+ * Cliente de Apipos, el agente local de impresión que corre en la caja
+ * (por defecto en http://127.0.0.1:50432). Envuelve los endpoints de
+ * APIPOS_API.md y crea las impresoras (`ApiPosPrinter`) que mandan los trabajos.
+ *
+ * La librería no sabe nada del POS que la usa: lo que cada app quiera hacerle al
+ * texto antes de imprimir (limpieza, quitar acentos) entra por el hook
+ * `transformContent`.
+ *
+ * Handshake de versión: cada respuesta trae `X-Apipos-Version`; si no coincide
+ * con la versión de la librería, avisa UNA vez por versión de Apipos: por
+ * defecto con `console.warn`, una vez por página; con `onVersionMismatch`, una
+ * vez por cliente.
+ */
+import { base64ToBlob, isRecord, isUnknownArray, request as sendRequest, unexpectedResponse } from './http.js';
+import { ApiPosPrinter } from './printer.js';
+import { VERSION } from './version.js';
+import { describeVersions } from './version-check.js';
+const DEFAULT_BASE_URL = 'http://127.0.0.1:50432';
+// El `fetch` global se busca en CADA petición, como en v1 (que llamaba a `fetch`
+// directo): si alguien lo reemplaza después de crear el cliente (dobles de
+// prueba, instrumentación), se usa el vigente. Se invoca como método de
+// `globalThis`, así el navegador no lanza "Illegal invocation".
+const globalFetch = (url, init) => globalThis.fetch(url, init);
+// Default de `transformContent`: copia superficial. Quien imprime puede reusar su
+// arreglo (otra copia, el reintento sin logo) y la librería nunca lo muta.
+const copyContent = content => content.slice();
+// Default de `onVersionMismatch`: el aviso a la consola del navegador. Busca
+// `console.warn` al avisar (no al crear el cliente), así se puede interceptar.
+const warnInConsole = (info) => {
+    console.warn(info.message);
+};
+// Versiones de Apipos (`String(info.backend)`; `'null'` = no la reporta) ya
+// avisadas con el `console.warn` por defecto. Vive en el MÓDULO, no en cada
+// cliente: una app puede crear un `new Apipos()` por impresión y el aviso debe
+// salir una vez por página, no en cada ticket.
+const warnedInConsole = new Set();
+function isVersionStatus(value) {
+    return value === 'equal' || value === 'client_older' || value === 'client_newer' || value === 'unknown';
+}
+function isStringOrNull(value) {
+    return value === null || typeof value === 'string';
+}
+function isServerClientStatus(value) {
+    return (isRecord(value) &&
+        isStringOrNull(value.name) &&
+        isStringOrNull(value.version) &&
+        typeof value.server === 'string' &&
+        isVersionStatus(value.status) &&
+        typeof value.message === 'string');
+}
+// `version` y `client` no existen en Apipos anteriores a 1.0.6: su ausencia no
+// es un error (justo con esos backends importa que checkHealth siga funcionando).
+function isHealthData(value) {
+    return (isRecord(value) &&
+        typeof value.status === 'string' &&
+        typeof value.os === 'string' &&
+        typeof value.platform === 'string' &&
+        typeof value.backend === 'string' &&
+        typeof value.port === 'number' &&
+        (value.version === undefined || typeof value.version === 'string') &&
+        (value.client === undefined || value.client === null || isServerClientStatus(value.client)));
+}
+function isStringArray(value) {
+    return isUnknownArray(value) && value.every(item => typeof item === 'string');
+}
+function isFontFormat(value) {
+    return value === 'ttf' || value === 'otf' || value === 'ttc' || value === 'otc';
+}
+function isFontFace(value) {
+    return (isRecord(value) &&
+        typeof value.style === 'string' &&
+        typeof value.bold === 'boolean' &&
+        typeof value.italic === 'boolean' &&
+        typeof value.weight === 'number' &&
+        typeof value.full_name === 'string' &&
+        isStringOrNull(value.postscript_name) &&
+        typeof value.path === 'string' &&
+        typeof value.index === 'number' &&
+        isFontFormat(value.format));
+}
+function isFontFamily(value) {
+    return (isRecord(value) &&
+        typeof value.family === 'string' &&
+        typeof value.monospace === 'boolean' &&
+        isUnknownArray(value.faces) &&
+        value.faces.every(isFontFace));
+}
+/** Forma de `data` de GET /fonts (APIPOS_API.md, "Fuentes del sistema"). */
+function isFontCatalogData(value) {
+    return (isRecord(value) &&
+        isUnknownArray(value.families) &&
+        value.families.every(isFontFamily) &&
+        typeof value.count === 'number' &&
+        isStringArray(value.builtin) &&
+        isStringArray(value.dirs) &&
+        typeof value.scanned_at === 'string');
+}
+function isRenderFormat(value) {
+    return value === 'pdf' || value === 'png';
+}
+function isFontSource(value) {
+    return value === 'system' || value === 'builtin' || value === 'fallback';
+}
+function isRenderedFont(value) {
+    return (isRecord(value) &&
+        typeof value.family === 'string' &&
+        typeof value.resolved === 'string' &&
+        isFontSource(value.source) &&
+        typeof value.bold === 'boolean' &&
+        typeof value.italic === 'boolean');
+}
+function isPageSizeMm(value) {
+    return isRecord(value) && typeof value.width === 'number' && typeof value.height === 'number';
+}
+/** Forma de `data` de POST /render (APIPOS_API.md, "Vista previa"). `dpi` es `null` con `pdf`. */
+function isRenderData(value) {
+    return (isRecord(value) &&
+        isRenderFormat(value.format) &&
+        (value.dpi === null || typeof value.dpi === 'number') &&
+        typeof value.base64 === 'string' &&
+        isPageSizeMm(value.page_mm) &&
+        typeof value.pages === 'number' &&
+        isUnknownArray(value.fonts) &&
+        value.fonts.every(isRenderedFont) &&
+        isStringArray(value.warnings));
+}
+// Mime del `blob` de una vista previa según el formato que devolvió Apipos.
+const RENDER_MIME = { pdf: 'application/pdf', png: 'image/png' };
+export class Apipos {
+    #baseUrl;
+    #fetch;
+    #transformContent;
+    #onVersionMismatch;
+    // Con `onVersionMismatch` inyectado, las versiones ya avisadas son de ESTE
+    // cliente: quien inyecta el hook controla su propia política.
+    #warnedBackends = new Set();
+    constructor(options = {}) {
+        this.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.#fetch = options.fetch ?? globalFetch;
+        this.#transformContent = options.transformContent ?? copyContent;
+        this.#onVersionMismatch = options.onVersionMismatch ?? null;
+    }
+    /** URL base de Apipos (default `http://127.0.0.1:50432`). */
+    get baseUrl() {
+        return this.#baseUrl;
+    }
+    /** Alias de `baseUrl` (compatibilidad con v1). */
+    get apiUrl() {
+        return this.#baseUrl;
+    }
+    /** Compatibilidad con v1: cambia la URL base para las siguientes peticiones. */
+    set apiUrl(url) {
+        this.#baseUrl = url;
+    }
+    /**
+     * Verifica que el servicio de impresión esté disponible.
+     * GET /health → { data: { status, version, os, platform, backend, port, client }, message, status }
+     *
+     * Devuelve `{ ok, data, version }`: `ok` es `true` si el servicio responde
+     * "ok" y `version` = `describeVersions(VERSION, data.version)`
+     * (`{ client, backend, status, message }`).
+     *
+     * `data.version` pasa por el MISMO aviso deduplicado que el header: si el
+     * header ya avisó esa versión no se repite, y si la respuesta no trajo
+     * `headers` (dobles de `fetch`) el aviso sale de aquí.
+     *
+     * Nunca lanza: ante cualquier error devuelve `{ ok: false, data: null, version: null }`.
+     */
+    async checkHealth() {
+        try {
+            const data = await this.request('GET', '/health');
+            if (!isHealthData(data))
+                throw unexpectedResponse('/health');
+            const version = describeVersions(VERSION, data.version ?? null);
+            this.#notifyVersion(version);
+            return { ok: data.status === 'ok', data, version };
+        }
+        catch (e) {
+            console.error('Error checking Apipos health:', e);
+            return { ok: false, data: null, version: null };
+        }
+    }
+    /** GET /printers → nombres exactos de las impresoras instaladas; `[]` si falla. */
+    async listPrinters() {
+        try {
+            const data = await this.request('GET', '/printers');
+            if (!isStringArray(data))
+                throw unexpectedResponse('/printers');
+            return data;
+        }
+        catch (e) {
+            console.error('Error fetching printers:', e);
+            return [];
+        }
+    }
+    /**
+     * Fuentes instaladas en la máquina de Apipos, para elegir `settings.font.family`
+     * o `font_family` del renderizador PDF.
+     * GET /fonts (con `refresh: true` → GET /fonts?refresh=1, que vuelve a
+     * escanear; útil tras instalar una fuente).
+     *
+     * Devuelve `{ families, builtin, count, dirs, scannedAt }`: `builtin`
+     * (`sans-serif`, `serif`, `monospace`) existe siempre, aunque la máquina no
+     * tenga fuentes. A diferencia de `listPrinters`, LANZA ante cualquier error
+     * (`ApiposError`, sin conexión o `Respuesta inesperada de Apipos en /fonts`).
+     */
+    async listFonts({ refresh = false } = {}) {
+        const data = await this.request('GET', '/fonts', refresh ? { query: { refresh: true } } : {});
+        if (!isFontCatalogData(data))
+            throw unexpectedResponse('/fonts');
+        return {
+            families: data.families,
+            builtin: data.builtin,
+            count: data.count,
+            dirs: data.dirs,
+            scannedAt: data.scanned_at
+        };
+    }
+    /**
+     * Vista previa REAL de un ticket: Apipos lo maqueta con el mismo renderizador
+     * PDF que imprime (`settings.renderer: 'pdf'`), sin validar ni tocar ninguna
+     * impresora. POST /render con `{ settings, content, format, dpi }`.
+     *
+     * `content` pasa por `transformContent`, igual que al imprimir: lo que se ve
+     * es lo que saldría en papel. `dpi` solo aplica con `png` (72–600).
+     *
+     * Devuelve `{ format, dpi, base64, pageMm, pages, fonts, warnings, blob }`;
+     * `blob` es un `Blob` `application/pdf` o `image/png` listo para
+     * `URL.createObjectURL`, y `dpi` es `null` con `pdf`. Lanza ante cualquier error.
+     */
+    async renderTicket(content, { settings = {}, format = 'pdf', dpi = 203 } = {}) {
+        const data = await this.request('POST', '/render', {
+            body: { settings, content: this.applyTransform(content), format, dpi }
+        });
+        if (!isRenderData(data))
+            throw unexpectedResponse('/render');
+        return {
+            format: data.format,
+            dpi: data.dpi,
+            base64: data.base64,
+            pageMm: data.page_mm,
+            pages: data.pages,
+            fonts: data.fonts,
+            warnings: data.warnings,
+            blob: base64ToBlob(data.base64, RENDER_MIME[data.format])
+        };
+    }
+    /**
+     * Impresora con nombre exacto (de `listPrinters()`) y sus `settings`
+     * (`paper_size` numérico obligatorio). Sin nombre devuelve `null` y lo
+     * reporta en consola, como v1.
+     */
+    createPrinter(name, settings = {}) {
+        if (!name) {
+            console.error('Printer name is required');
+            return null;
+        }
+        return new ApiPosPrinter(name, settings, this);
+    }
+    /**
+     * Acceso a la red para `ApiPosPrinter` (y para endpoints que la librería aún
+     * no envuelve): devuelve el `data` del sobre o lanza `ApiposError`.
+     */
+    request(method, path, options) {
+        return sendRequest({ baseUrl: this.#baseUrl, fetch: this.#fetch, onVersion: info => this.#notifyVersion(info) }, method, path, options);
+    }
+    /** Pasa el `content` de un trabajo por `transformContent`. */
+    applyTransform(content) {
+        return this.#transformContent(content);
+    }
+    // Aviso de versión: solo si difieren y una vez por versión de Apipos (por
+    // página con el aviso por defecto; por cliente con `onVersionMismatch`). Es
+    // informativo: si `onVersionMismatch` lanza, se reporta y la petición (la
+    // impresión) sigue su curso.
+    #notifyVersion(info) {
+        if (info.status === 'equal')
+            return;
+        const key = String(info.backend);
+        const warned = this.#onVersionMismatch ? this.#warnedBackends : warnedInConsole;
+        if (warned.has(key))
+            return;
+        warned.add(key);
+        try {
+            (this.#onVersionMismatch ?? warnInConsole)(info);
+        }
+        catch (e) {
+            console.error('Error in Apipos onVersionMismatch:', e);
+        }
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,36 @@
+import type { HttpMethod, RequestContext, RequestOptions } from './types.js';
+export declare const CLIENT_HEADER = "X-Apipos-Client";
+export declare const VERSION_HEADER = "X-Apipos-Version";
+export declare const CONNECT_ERROR: (baseUrl: string) => string;
+/**
+ * Error de negocio que respondió Apipos (`status: 'error'` o HTTP no-2xx).
+ * `message` es el del backend (p. ej. `Printer 'X' not found.`) y `data` lo que
+ * traiga el sobre (p. ej. `{ available: [...] }` con las impresoras válidas).
+ * Sigue siendo `instanceof Error`.
+ */
+export declare class ApiposError extends Error {
+    data: unknown;
+    constructor(message: string, data?: unknown);
+}
+/** Objeto JSON (no `null`). Los arreglos también pasan: se leen sus claves como `undefined`. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** `Array.isArray` sin dejar escapar elementos sin tipo. */
+export declare function isUnknownArray(value: unknown): value is readonly unknown[];
+/** Error para cuando Apipos respondió éxito pero con una forma que no es la del contrato. */
+export declare function unexpectedResponse(path: string): Error;
+/**
+ * base64 (puro o data URI `data:<mime>;base64,...`) → `Blob` del `mime` dado
+ * (el del data URI se descarta). Usa `atob`, que existe en el navegador y en
+ * Node: así lo que devuelve `POST /render` se puede abrir, descargar o mostrar
+ * con `URL.createObjectURL(blob)`. Un base64 inválido lanza el error de `atob`.
+ */
+export declare function base64ToBlob(base64: string, mime: string): Blob;
+/**
+ * Único punto de red de la librería. Manda `X-Apipos-Client: apipos-js/<VERSION>`,
+ * evalúa `X-Apipos-Version` (handshake: `ctx.onVersion`), interpreta el sobre
+ * `{ status, data, message }` y devuelve `data` (o `null`), o lanza
+ * `ApiposError(message)` con `error.data` (p. ej. `available`).
+ *
+ * @param path  p. ej. `'/print'`
+ */
+export declare function request(ctx: RequestContext, method: HttpMethod, path: string, { body, query }?: RequestOptions): Promise<unknown>;

package/dist/http.js

@@ -0,0 +1,113 @@
+/*
+ * Único punto de red de la librería: todo lo que habla con Apipos pasa por
+ * `request()`. Aquí viven el header del cliente, el handshake de versión, el
+ * manejo del sobre `{ status, data, message }` y los mensajes de error que ve
+ * el usuario del POS.
+ */
+import { CLIENT_NAME, VERSION } from './version.js';
+import { describeVersions } from './version-check.js';
+export const CLIENT_HEADER = 'X-Apipos-Client';
+export const VERSION_HEADER = 'X-Apipos-Version';
+export const CONNECT_ERROR = (baseUrl) => `No se pudo conectar con Apipos (${baseUrl}). ¿Está abierta la app de bandeja?`;
+/**
+ * Error de negocio que respondió Apipos (`status: 'error'` o HTTP no-2xx).
+ * `message` es el del backend (p. ej. `Printer 'X' not found.`) y `data` lo que
+ * traiga el sobre (p. ej. `{ available: [...] }` con las impresoras válidas).
+ * Sigue siendo `instanceof Error`.
+ */
+export class ApiposError extends Error {
+    data;
+    constructor(message, data = null) {
+        super(message);
+        this.name = 'ApiposError';
+        this.data = data;
+    }
+}
+/** Objeto JSON (no `null`). Los arreglos también pasan: se leen sus claves como `undefined`. */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** `Array.isArray` sin dejar escapar elementos sin tipo. */
+export function isUnknownArray(value) {
+    return Array.isArray(value);
+}
+/** Error para cuando Apipos respondió éxito pero con una forma que no es la del contrato. */
+export function unexpectedResponse(path) {
+    return new Error(`Respuesta inesperada de Apipos en ${path}`);
+}
+// Prefijo de un data URI en base64 (`data:image/png;base64,`), con o sin mime.
+const DATA_URI_PREFIX = /^data:[^,]*;base64,/i;
+/**
+ * base64 (puro o data URI `data:<mime>;base64,...`) → `Blob` del `mime` dado
+ * (el del data URI se descarta). Usa `atob`, que existe en el navegador y en
+ * Node: así lo que devuelve `POST /render` se puede abrir, descargar o mostrar
+ * con `URL.createObjectURL(blob)`. Un base64 inválido lanza el error de `atob`.
+ */
+export function base64ToBlob(base64, mime) {
+    const binary = atob(base64.replace(DATA_URI_PREFIX, ''));
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return new Blob([bytes], { type: mime });
+}
+function queryString(query) {
+    if (!query)
+        return '';
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === null || value === undefined)
+            continue;
+        params.append(key, typeof value === 'boolean' ? (value ? '1' : '0') : String(value));
+    }
+    const text = params.toString();
+    return text ? `?${text}` : '';
+}
+/**
+ * Único punto de red de la librería. Manda `X-Apipos-Client: apipos-js/<VERSION>`,
+ * evalúa `X-Apipos-Version` (handshake: `ctx.onVersion`), interpreta el sobre
+ * `{ status, data, message }` y devuelve `data` (o `null`), o lanza
+ * `ApiposError(message)` con `error.data` (p. ej. `available`).
+ *
+ * @param path  p. ej. `'/print'`
+ */
+export async function request(ctx, method, path, { body, query } = {}) {
+    const headers = { [CLIENT_HEADER]: `${CLIENT_NAME}/${VERSION}` };
+    const init = { method, headers };
+    if (body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        init.body = JSON.stringify(body);
+    }
+    // Se llama suelta (no como `ctx.fetch(...)`): un `fetch` nativo inyectado tal
+    // cual (`{ fetch: window.fetch }`) falla con "Illegal invocation" si recibe
+    // otro objeto como `this`.
+    const send = ctx.fetch;
+    let response;
+    try {
+        response = await send(ctx.baseUrl + path + queryString(query), init);
+    }
+    catch {
+        throw new Error(CONNECT_ERROR(ctx.baseUrl));
+    }
+    let payload = null;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        // respuesta sin cuerpo JSON
+    }
+    // Handshake: TODA respuesta de Apipos ≥ 1.0.6 trae `X-Apipos-Version` (también
+    // las de error, por eso va antes de lanzar). Sin el header → `unknown`: es un
+    // Apipos anterior. Si la respuesta no trae `headers` (dobles de `fetch` de
+    // pruebas) no hay nada que comparar y no se evalúa.
+    if (response.headers) {
+        ctx.onVersion?.(describeVersions(VERSION, response.headers.get(VERSION_HEADER)));
+    }
+    const envelope = isRecord(payload) ? payload : null;
+    const data = envelope?.data ?? null;
+    if (!response.ok || envelope?.status === 'error') {
+        const message = envelope?.message;
+        throw new ApiposError((typeof message === 'string' && message) || response.statusText || 'Error de impresión', data);
+    }
+    return data;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { Apipos } from './apipos.js';
+export { ApiPosPrinter } from './printer.js';
+export { VERSION, CLIENT_NAME } from './version.js';
+export { parseVersion, compareVersions, describeVersions } from './version-check.js';
+export { ApiposError, base64ToBlob } from './http.js';
+export { stripAccents, stripAccentsFromContent } from './strip-accents.js';
+export { ticketColumns, TICKET_PREVIEW_CSS, renderTicketHtml, printTicketHtml, renderTicketPreviewPng } from './ticket-preview.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// API pública de @tecsom/apipos-js. Lo que no se exporta aquí (ni en los
+// subpaths de package.json) es interno y puede cambiar sin aviso.
+export { Apipos } from './apipos.js';
+export { ApiPosPrinter } from './printer.js';
+export { VERSION, CLIENT_NAME } from './version.js';
+export { parseVersion, compareVersions, describeVersions } from './version-check.js';
+export { ApiposError, base64ToBlob } from './http.js';
+export { stripAccents, stripAccentsFromContent } from './strip-accents.js';
+export { ticketColumns, TICKET_PREVIEW_CSS, renderTicketHtml, printTicketHtml, renderTicketPreviewPng } from './ticket-preview.js';

package/dist/printer.d.ts

@@ -0,0 +1,61 @@
+import type { Apipos } from './apipos.js';
+import type { OpenDrawerResult, PrinterRenderOptions, PrintOptions, PrintPdfOptions, PrintResult, PrintSettings, RenderResult, TicketContent } from './types.js';
+export declare class ApiPosPrinter {
+    #private;
+    settings: PrintSettings;
+    /**
+     * 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: string, settings: PrintSettings | undefined, apipos: Apipos);
+    validateSettings(): void;
+    get name(): string;
+    get apiUrl(): string;
+    /**
+     * 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.
+     */
+    print(content: TicketContent, options?: PrintOptions): Promise<PrintResult | null>;
+    /**
+     * 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.`).
+     */
+    openDrawer(): Promise<OpenDrawerResult>;
+    /**
+     * 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).
+     */
+    render(content: TicketContent, { format, dpi, ...options }?: PrinterRenderOptions): Promise<RenderResult>;
+    /**
+     * 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.
+     */
+    printPDF(blob: Blob, { pdfMode, labelSettings }?: PrintPdfOptions): Promise<PrintResult | null>;
+}