@technestinnovations/print-gateway-client 1.0.0

package/dist/schema.d.ts

@@ -0,0 +1,126 @@
+export type PrintDocumentBlock = {
+    type: 'text';
+    value: string;
+    align?: 'left' | 'center' | 'right';
+    style?: {
+        bold?: boolean;
+        width?: number;
+        height?: number;
+    };
+} | {
+    type: 'rule';
+    char?: string;
+    style?: string;
+} | {
+    type: 'row';
+    columns: Array<{
+        text: string;
+        width: number;
+        align?: string;
+        style?: {
+            bold?: boolean;
+        };
+    }>;
+} | {
+    type: 'table';
+    headers?: string[];
+    rows: string[][];
+} | {
+    type: 'image';
+    data: string;
+    align?: string;
+    max_width?: number;
+} | {
+    type: 'qr';
+    data: string;
+    size?: number;
+    align?: string;
+} | {
+    type: 'barcode';
+    data: string;
+    format?: string;
+    align?: string;
+    height?: number;
+} | {
+    type: 'feed';
+    lines?: number;
+} | {
+    type: 'cut';
+    mode?: 'full' | 'partial';
+} | {
+    type: 'cash_drawer';
+    pin?: number;
+};
+export type PrintDocument = {
+    schema_version?: string;
+    document_type?: string;
+    paper_width_mm?: number;
+    locale?: string;
+    metadata?: Record<string, unknown>;
+    blocks: PrintDocumentBlock[];
+};
+export type PrintOptions = {
+    copies?: number;
+    cut?: boolean;
+    cut_mode?: 'full' | 'partial' | 'none';
+    open_cash_drawer?: boolean;
+    cash_drawer_pin?: number;
+    feed_lines_before_cut?: number;
+};
+export type PrintRequest = {
+    document: PrintDocument;
+    printer_id?: string;
+    role?: string;
+    options?: PrintOptions;
+};
+export type PrintJobResponse = {
+    job_id: string;
+    status: string;
+    printer_id: string;
+    created_at: string;
+};
+export type GatewayDestination = {
+    destination: string;
+    printer_id: string;
+    name: string;
+};
+export type GatewayPrinter = {
+    printer_id: string;
+    name: string;
+    last_known_ip: string;
+    port: number;
+    protocol: string;
+    roles: string[];
+    is_default: boolean;
+    connection_status: string;
+    paper_width_mm: number;
+    cut_mode: string;
+    open_cash_drawer: boolean;
+};
+export type GatewayHealth = {
+    status: string;
+    service: string;
+    version: string;
+    api_version: string;
+    schema_version: string;
+    requires_auth: boolean;
+    transport_mode: string;
+    uptime_seconds?: number;
+    host?: string;
+    port?: number;
+    printer_count?: number;
+    default_printer_id?: string;
+    destinations?: GatewayDestination[];
+    pos_origins_configured?: boolean;
+    pos_origin_count?: number;
+};
+export type SetupBundle = {
+    base_url: string;
+    pos_origin: string;
+    printers: Array<{
+        printer_id: string;
+        name: string;
+        destinations: string[];
+        is_default: boolean;
+    }>;
+};

package/dist/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/setup.d.ts

@@ -0,0 +1,31 @@
+import { PrintGatewayClient } from './print.js';
+import type { GatewayDestination, GatewayHealth, PrintDocument, PrintJobResponse, SetupBundle } from './schema.js';
+export type SetupValidation = {
+    ok: boolean;
+    printerCount: number;
+    defaultPrinterId?: string;
+    destinations: GatewayDestination[];
+};
+export declare function validateSetup(client: PrintGatewayClient): Promise<SetupValidation>;
+export declare function parseSetupBundle(raw: string): SetupBundle;
+export type PrintRouterOptions = {
+    client: PrintGatewayClient;
+    routes: Record<string, string>;
+};
+export type PrintRouteOptions = {
+    idempotencyKey?: string;
+    waitForCompletion?: boolean;
+};
+export declare function createPrintRouter(options: PrintRouterOptions): {
+    routes: Record<string, string>;
+    getPrinterId(routeKey: string): string | undefined;
+    print(routeKey: string, document: PrintDocument, printOptions?: PrintRouteOptions): Promise<PrintJobResponse>;
+};
+export declare function resolvePrintTarget(client: PrintGatewayClient, options: {
+    printerId?: string;
+    role?: string;
+    health?: GatewayHealth;
+}): Promise<{
+    printerId?: string;
+    role?: string;
+}>;

package/dist/setup.js

@@ -0,0 +1,49 @@
+export async function validateSetup(client) {
+    const health = await client.getHealth();
+    return {
+        ok: health.status === 'ok',
+        printerCount: health.printer_count ?? 0,
+        defaultPrinterId: health.default_printer_id,
+        destinations: health.destinations ?? [],
+    };
+}
+export function parseSetupBundle(raw) {
+    const parsed = JSON.parse(raw);
+    if (!parsed.base_url || !parsed.pos_origin || !Array.isArray(parsed.printers)) {
+        throw new Error('Invalid setup bundle');
+    }
+    return parsed;
+}
+export function createPrintRouter(options) {
+    const { client, routes } = options;
+    return {
+        routes,
+        getPrinterId(routeKey) {
+            return routes[routeKey];
+        },
+        async print(routeKey, document, printOptions = {}) {
+            const printerId = routes[routeKey];
+            if (!printerId) {
+                throw new Error(`No printer mapped for route "${routeKey}"`);
+            }
+            const job = await client.print({ document, printer_id: printerId }, printOptions.idempotencyKey);
+            if (printOptions.waitForCompletion) {
+                return client.waitForJob(job.job_id);
+            }
+            return job;
+        },
+    };
+}
+export async function resolvePrintTarget(client, options) {
+    if (options.printerId) {
+        return { printerId: options.printerId };
+    }
+    const health = options.health ?? await client.getHealth();
+    if (!options.role && health.printer_count === 1 && health.default_printer_id) {
+        return { printerId: health.default_printer_id };
+    }
+    if (options.role) {
+        return { role: options.role };
+    }
+    return { role: 'receipt' };
+}

package/dist/src/adapters/receiptAdapter.d.ts

@@ -0,0 +1,27 @@
+import type { PrintDocument } from '../schema';
+export type ReceiptLineItem = {
+    name: string;
+    quantity: number;
+    unitPrice: number;
+    total: number;
+};
+export type ReceiptData = {
+    storeName: string;
+    storeAddress?: string;
+    storePhone?: string;
+    receiptNumber: string;
+    orderId?: string;
+    tableName?: string;
+    timestamp: string;
+    items: ReceiptLineItem[];
+    subtotal?: number;
+    discount?: number;
+    tax?: number;
+    total: number;
+    paymentMethod?: string;
+    customerName?: string;
+    footer?: string;
+    qrUrl?: string;
+    paperWidthMm?: number;
+};
+export declare function buildReceiptDocument(data: ReceiptData): PrintDocument;

package/dist/src/adapters/receiptAdapter.js

@@ -0,0 +1,100 @@
+export function buildReceiptDocument(data) {
+    const paperWidth = data.paperWidthMm ?? 80;
+    const blocks = [
+        { type: 'text', value: data.storeName, align: 'center', style: { bold: true, width: 2, height: 2 } },
+    ];
+    if (data.storeAddress) {
+        blocks.push({ type: 'text', value: data.storeAddress, align: 'center' });
+    }
+    if (data.storePhone) {
+        blocks.push({ type: 'text', value: data.storePhone, align: 'center' });
+    }
+    const header = [
+        `Bill #${data.receiptNumber}`,
+        data.tableName ? `Table ${data.tableName}` : null,
+    ].filter(Boolean).join(' · ');
+    blocks.push({ type: 'text', value: header, align: 'center' });
+    blocks.push({ type: 'text', value: data.timestamp, align: 'center' });
+    blocks.push({ type: 'rule' });
+    for (const item of data.items) {
+        blocks.push({
+            type: 'row',
+            columns: [
+                { text: item.name, width: 60, align: 'left' },
+                { text: item.total.toFixed(2), width: 40, align: 'right' },
+            ],
+        });
+        blocks.push({
+            type: 'row',
+            columns: [
+                { text: `  ${item.quantity} x ${item.unitPrice.toFixed(2)}`, width: 60, align: 'left' },
+                { text: '', width: 40, align: 'right' },
+            ],
+        });
+    }
+    blocks.push({ type: 'rule' });
+    if (data.subtotal != null) {
+        blocks.push({
+            type: 'row',
+            columns: [
+                { text: 'Subtotal', width: 60, align: 'left' },
+                { text: data.subtotal.toFixed(2), width: 40, align: 'right' },
+            ],
+        });
+    }
+    if (data.discount != null) {
+        blocks.push({
+            type: 'row',
+            columns: [
+                { text: 'Discount', width: 60, align: 'left' },
+                { text: data.discount.toFixed(2), width: 40, align: 'right' },
+            ],
+        });
+    }
+    if (data.tax != null) {
+        blocks.push({
+            type: 'row',
+            columns: [
+                { text: 'Tax', width: 60, align: 'left' },
+                { text: data.tax.toFixed(2), width: 40, align: 'right' },
+            ],
+        });
+    }
+    blocks.push({
+        type: 'row',
+        columns: [
+            { text: 'GRAND TOTAL', width: 60, align: 'left', style: { bold: true } },
+            { text: data.total.toFixed(2), width: 40, align: 'right', style: { bold: true } },
+        ],
+    });
+    if (data.paymentMethod) {
+        blocks.push({ type: 'text', value: `PAID · ${data.paymentMethod}`, align: 'left' });
+    }
+    if (data.customerName) {
+        blocks.push({ type: 'text', value: data.customerName, align: 'left' });
+    }
+    if (data.footer) {
+        blocks.push({ type: 'text', value: data.footer, align: 'center' });
+    }
+    if (data.qrUrl) {
+        blocks.push({ type: 'qr', data: data.qrUrl, size: 6, align: 'center' });
+    }
+    blocks.push({ type: 'feed', lines: 3 });
+    blocks.push({ type: 'cut', mode: 'full' });
+    return {
+        schema_version: '1.0',
+        document_type: 'receipt',
+        paper_width_mm: paperWidth,
+        metadata: {
+            receipt_number: data.receiptNumber,
+            order_id: data.orderId,
+            timestamp: data.timestamp,
+            store: {
+                name: data.storeName,
+                address: data.storeAddress,
+                phone: data.storePhone,
+            },
+        },
+        blocks,
+    };
+}

package/dist/src/detect.d.ts

@@ -0,0 +1,12 @@
+import type { GatewayHealth } from './schema';
+export type DetectOptions = {
+    baseUrl?: string;
+    timeoutMs?: number;
+};
+export type DetectResult = {
+    available: boolean;
+    health?: GatewayHealth;
+    baseUrl: string;
+};
+export declare function detectPrintGateway(options?: DetectOptions): Promise<DetectResult>;
+export declare function isAndroidDevice(): boolean;

package/dist/src/detect.js

@@ -0,0 +1,24 @@
+const DEFAULT_BASE_URL = 'http://127.0.0.1:19643/api/v1';
+export async function detectPrintGateway(options = {}) {
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    const timeoutMs = options.timeoutMs ?? 500;
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(`${baseUrl}/health`, { signal: controller.signal });
+        clearTimeout(timer);
+        if (!response.ok) {
+            return { available: false, baseUrl };
+        }
+        const health = (await response.json());
+        return { available: health.status === 'ok', health, baseUrl };
+    }
+    catch {
+        return { available: false, baseUrl };
+    }
+}
+export function isAndroidDevice() {
+    if (typeof navigator === 'undefined')
+        return false;
+    return /Android/i.test(navigator.userAgent);
+}

package/dist/src/fallback.d.ts

@@ -0,0 +1,4 @@
+export type FallbackPrintOptions = {
+    title?: string;
+};
+export declare function fallbackWindowPrint(options?: FallbackPrintOptions): Promise<void>;

package/dist/src/fallback.js

@@ -0,0 +1,13 @@
+export function fallbackWindowPrint(options = {}) {
+    return new Promise((resolve, reject) => {
+        if (typeof window === 'undefined' || typeof window.print !== 'function') {
+            reject(new Error('window.print is not available'));
+            return;
+        }
+        if (options.title && typeof document !== 'undefined') {
+            document.title = options.title;
+        }
+        window.print();
+        resolve();
+    });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,24 @@
+import type { PrintDocument } from './schema';
+export { buildReceiptDocument } from './adapters/receiptAdapter';
+export type { ReceiptData, ReceiptLineItem } from './adapters/receiptAdapter';
+export { detectPrintGateway, isAndroidDevice } from './detect';
+export { fallbackWindowPrint } from './fallback';
+export { PrintGatewayClient } from './print';
+export type { GatewayHealth, PrintDocument, PrintDocumentBlock, PrintJobResponse, PrintOptions, PrintRequest, } from './schema';
+export type PrintWithFallbackOptions = {
+    baseUrl?: string;
+    authToken?: string;
+    printerId?: string;
+    role?: string;
+    idempotencyKey?: string;
+    waitForCompletion?: boolean;
+    onlyOnAndroid?: boolean;
+};
+export type PrintResult = {
+    method: 'gateway';
+    jobId: string;
+    status: string;
+} | {
+    method: 'window.print';
+};
+export declare function printWithFallback(document: PrintDocument, options?: PrintWithFallbackOptions): Promise<PrintResult>;

package/dist/src/index.js

@@ -0,0 +1,35 @@
+import { detectPrintGateway, isAndroidDevice } from './detect';
+import { fallbackWindowPrint } from './fallback';
+import { PrintGatewayClient } from './print';
+export { buildReceiptDocument } from './adapters/receiptAdapter';
+export { detectPrintGateway, isAndroidDevice } from './detect';
+export { fallbackWindowPrint } from './fallback';
+export { PrintGatewayClient } from './print';
+export async function printWithFallback(document, options = {}) {
+    const onlyOnAndroid = options.onlyOnAndroid ?? true;
+    if (onlyOnAndroid && !isAndroidDevice()) {
+        await fallbackWindowPrint();
+        return { method: 'window.print' };
+    }
+    const detection = await detectPrintGateway({ baseUrl: options.baseUrl });
+    if (!detection.available) {
+        await fallbackWindowPrint();
+        return { method: 'window.print' };
+    }
+    const client = new PrintGatewayClient({
+        baseUrl: detection.baseUrl,
+        authToken: options.authToken,
+    });
+    const request = {
+        document,
+        printer_id: options.printerId,
+        role: options.role ?? 'receipt',
+        options: { cut: true },
+    };
+    const job = await client.print(request, options.idempotencyKey);
+    if (options.waitForCompletion) {
+        const finalJob = await client.waitForJob(job.job_id);
+        return { method: 'gateway', jobId: finalJob.job_id, status: finalJob.status };
+    }
+    return { method: 'gateway', jobId: job.job_id, status: job.status };
+}

package/dist/src/print.d.ts

@@ -0,0 +1,18 @@
+import type { PrintJobResponse, PrintRequest } from './schema';
+export type PrintGatewayClientOptions = {
+    baseUrl?: string;
+    authToken?: string;
+};
+export declare class PrintGatewayClient {
+    private baseUrl;
+    private authToken?;
+    constructor(options?: PrintGatewayClientOptions);
+    setAuthToken(token: string): void;
+    private headers;
+    print(request: PrintRequest, idempotencyKey?: string): Promise<PrintJobResponse>;
+    getJob(jobId: string): Promise<PrintJobResponse & {
+        attempts?: number;
+        last_error?: string;
+    }>;
+    waitForJob(jobId: string, timeoutMs?: number, pollMs?: number): Promise<PrintJobResponse>;
+}

package/dist/src/print.js

@@ -0,0 +1,53 @@
+export class PrintGatewayClient {
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl ?? 'http://127.0.0.1:19643/api/v1';
+        this.authToken = options.authToken;
+    }
+    setAuthToken(token) {
+        this.authToken = token;
+    }
+    headers(idempotencyKey) {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.authToken) {
+            headers.Authorization = `Bearer ${this.authToken}`;
+        }
+        if (idempotencyKey) {
+            headers['X-Idempotency-Key'] = idempotencyKey;
+        }
+        return headers;
+    }
+    async print(request, idempotencyKey) {
+        const response = await fetch(`${this.baseUrl}/print`, {
+            method: 'POST',
+            headers: this.headers(idempotencyKey),
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(body || `Print request failed with status ${response.status}`);
+        }
+        return (await response.json());
+    }
+    async getJob(jobId) {
+        const response = await fetch(`${this.baseUrl}/jobs/${jobId}`, {
+            headers: this.headers(),
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch job ${jobId}`);
+        }
+        return (await response.json());
+    }
+    async waitForJob(jobId, timeoutMs = 30000, pollMs = 500) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const job = await this.getJob(jobId);
+            if (job.status === 'completed' || job.status === 'failed') {
+                return job;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+        throw new Error(`Timed out waiting for job ${jobId}`);
+    }
+}

package/dist/src/schema.d.ts

@@ -0,0 +1,88 @@
+export type PrintDocumentBlock = {
+    type: 'text';
+    value: string;
+    align?: 'left' | 'center' | 'right';
+    style?: {
+        bold?: boolean;
+        width?: number;
+        height?: number;
+    };
+} | {
+    type: 'rule';
+    char?: string;
+    style?: string;
+} | {
+    type: 'row';
+    columns: Array<{
+        text: string;
+        width: number;
+        align?: string;
+        style?: {
+            bold?: boolean;
+        };
+    }>;
+} | {
+    type: 'table';
+    headers?: string[];
+    rows: string[][];
+} | {
+    type: 'image';
+    data: string;
+    align?: string;
+    max_width?: number;
+} | {
+    type: 'qr';
+    data: string;
+    size?: number;
+    align?: string;
+} | {
+    type: 'barcode';
+    data: string;
+    format?: string;
+    align?: string;
+    height?: number;
+} | {
+    type: 'feed';
+    lines?: number;
+} | {
+    type: 'cut';
+    mode?: 'full' | 'partial';
+} | {
+    type: 'cash_drawer';
+    pin?: number;
+};
+export type PrintDocument = {
+    schema_version: string;
+    document_type: string;
+    paper_width_mm: number;
+    locale?: string;
+    metadata?: Record<string, unknown>;
+    blocks: PrintDocumentBlock[];
+};
+export type PrintOptions = {
+    copies?: number;
+    cut?: boolean;
+    open_cash_drawer?: boolean;
+};
+export type PrintRequest = {
+    document: PrintDocument;
+    printer_id?: string;
+    role?: string;
+    options?: PrintOptions;
+};
+export type PrintJobResponse = {
+    job_id: string;
+    status: string;
+    printer_id: string;
+    created_at: string;
+};
+export type GatewayHealth = {
+    status: string;
+    service: string;
+    version: string;
+    api_version: string;
+    schema_version: string;
+    requires_auth: boolean;
+    transport_mode: string;
+    default_printer_id?: string;
+};

package/dist/src/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/textToDocument.d.ts

@@ -0,0 +1,2 @@
+import type { PrintDocument } from './schema.js';
+export declare function textToDocument(text: string, documentType?: string): PrintDocument;

package/dist/textToDocument.js

@@ -0,0 +1,12 @@
+export function textToDocument(text, documentType = 'receipt') {
+    const blocks = text.replace(/\r\n/g, '\n').split('\n').map((line) => ({
+        type: 'text',
+        value: line,
+        align: 'left',
+    }));
+    return {
+        schema_version: '1.0',
+        document_type: documentType,
+        blocks,
+    };
+}

package/dist/textToDocument.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/textToDocument.test.js

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { textToDocument } from './textToDocument';
+import { buildPrintIntentUrl } from './intent';
+test('textToDocument splits lines without hardware fields', () => {
+    const document = textToDocument('Line 1\nLine 2');
+    assert.equal(document.blocks.length, 2);
+    assert.equal(document.paper_width_mm, undefined);
+    assert.equal(document.blocks[0]?.type, 'text');
+});
+test('buildPrintIntentUrl encodes payload', () => {
+    const url = buildPrintIntentUrl({
+        token: 'abc',
+        role: 'receipt',
+        document: textToDocument('Test'),
+    });
+    assert.match(url, /^printgateway:\/\/print\?payload=/);
+});