@technestinnovations/print-gateway-client 1.0.0

package/README.md

@@ -0,0 +1,35 @@
+# @technestinnovations/print-gateway-client
+
+Web POS client for the Android Print Gateway local HTTP API.
+
+## Usage
+
+```ts
+import { buildReceiptDocument, printWithFallback } from '@technestinnovations/print-gateway-client';
+
+const document = buildReceiptDocument({
+  storeName: 'MITHO SERVE',
+  receiptNumber: '123',
+  timestamp: new Date().toISOString(),
+  items: [{ name: 'Chicken Momo', quantity: 2, unitPrice: 250, total: 500 }],
+  total: 1400,
+  paymentMethod: 'Cash',
+});
+
+const result = await printWithFallback(document, {
+  baseUrl: 'http://127.0.0.1:19643/api/v1',
+  role: 'receipt',
+});
+```
+
+## Mixed content note
+
+If your web POS is served over HTTPS, `fetch('http://127.0.0.1:19643')` may be blocked by the browser. Options:
+
+1. Serve POS over HTTP on the Android device during testing
+2. Configure WebView mixed content for localhost if using a hybrid shell
+3. Fall back to `window.print()` automatically when the gateway is unavailable
+
+## POS origin
+
+Configure the POS website address in the Print Gateway app. Browser requests from that origin are allowed automatically.

package/dist/adapters/receiptAdapter.d.ts

@@ -0,0 +1,27 @@
+import type { PrintDocument } from '../schema.js';
+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/adapters/receiptAdapter.js

@@ -0,0 +1,97 @@
+export function buildReceiptDocument(data) {
+    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' });
+    }
+    return {
+        schema_version: '1.0',
+        document_type: 'receipt',
+        ...(data.paperWidthMm ? { paper_width_mm: data.paperWidthMm } : {}),
+        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/detect.d.ts

@@ -0,0 +1,12 @@
+import type { GatewayHealth } from './schema.js';
+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/detect.js

@@ -0,0 +1,27 @@
+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,
+            credentials: 'include',
+        });
+        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/detectDetailed.d.ts

@@ -0,0 +1,16 @@
+import type { GatewayHealth } from './schema.js';
+export type GatewayDetectHint = 'use_tablet' | 'start_service' | 'add_pos_origin' | 'https_blocked' | 'timeout' | 'unknown' | 'ok';
+export type GatewayDetectDetailed = {
+    reachable: boolean;
+    authorized: boolean;
+    isAndroid: boolean;
+    posOrigin: string;
+    gatewayBaseUrl: string;
+    health?: GatewayHealth;
+    hint: GatewayDetectHint;
+};
+export type DetectDetailedOptions = {
+    baseUrl?: string;
+    timeoutMs?: number;
+};
+export declare function detectPrintGatewayDetailed(options?: DetectDetailedOptions): Promise<GatewayDetectDetailed>;

package/dist/detectDetailed.js

@@ -0,0 +1,87 @@
+import { detectPrintGateway, isAndroidDevice } from './detect.js';
+async function probePrinters(baseUrl, timeoutMs) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(`${baseUrl}/printers`, {
+            signal: controller.signal,
+            credentials: 'include',
+        });
+        clearTimeout(timer);
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function detectPrintGatewayDetailed(options = {}) {
+    const gatewayBaseUrl = options.baseUrl ?? 'http://127.0.0.1:19643/api/v1';
+    const timeoutMs = options.timeoutMs ?? 3000;
+    const isAndroid = isAndroidDevice();
+    const posOrigin = typeof window !== 'undefined' ? window.location.origin : '';
+    if (!isAndroid) {
+        return {
+            reachable: false,
+            authorized: false,
+            isAndroid: false,
+            posOrigin,
+            gatewayBaseUrl,
+            hint: 'use_tablet',
+        };
+    }
+    if (typeof window !== 'undefined' && window.location.protocol === 'https:') {
+        // Mixed content may block http://127.0.0.1 — still try detect below.
+    }
+    let health;
+    let reachable = false;
+    let hint = 'unknown';
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const detection = await detectPrintGateway({
+            baseUrl: gatewayBaseUrl,
+            timeoutMs,
+        });
+        if (detection.available && detection.health) {
+            reachable = true;
+            health = detection.health;
+            break;
+        }
+        if (attempt === 0) {
+            await new Promise((resolve) => setTimeout(resolve, 200));
+        }
+    }
+    if (!reachable) {
+        if (typeof window !== 'undefined' && window.location.protocol === 'https:') {
+            hint = 'https_blocked';
+        }
+        else {
+            hint = 'start_service';
+        }
+        return {
+            reachable: false,
+            authorized: false,
+            isAndroid,
+            posOrigin,
+            gatewayBaseUrl,
+            hint,
+        };
+    }
+    const authorized = await probePrinters(gatewayBaseUrl, timeoutMs);
+    if (authorized) {
+        hint = 'ok';
+    }
+    else if (health?.pos_origins_configured === false) {
+        hint = 'add_pos_origin';
+    }
+    else {
+        hint = 'add_pos_origin';
+    }
+    return {
+        reachable: true,
+        authorized,
+        isAndroid,
+        posOrigin,
+        gatewayBaseUrl,
+        health,
+        hint: authorized ? 'ok' : hint,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export declare class PrintGatewayError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+export declare class AuthError extends PrintGatewayError {
+    constructor(message?: string);
+}
+export declare class RateLimitError extends PrintGatewayError {
+    constructor(message?: string);
+}
+export declare class NetworkError extends PrintGatewayError {
+    constructor(message?: string);
+}
+export declare class JobFailedError extends PrintGatewayError {
+    readonly jobId: string;
+    readonly lastError?: string;
+    constructor(jobId: string, lastError?: string);
+}
+export declare function parseApiError(status: number, body: string): PrintGatewayError;

package/dist/errors.js

@@ -0,0 +1,49 @@
+export class PrintGatewayError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.name = 'PrintGatewayError';
+        this.status = status;
+    }
+}
+export class AuthError extends PrintGatewayError {
+    constructor(message = 'Printing connection lost. Contact support to re-pair this device with your POS.') {
+        super(message, 401);
+        this.name = 'AuthError';
+    }
+}
+export class RateLimitError extends PrintGatewayError {
+    constructor(message = 'Print rate limit exceeded. Try again shortly.') {
+        super(message, 429);
+        this.name = 'RateLimitError';
+    }
+}
+export class NetworkError extends PrintGatewayError {
+    constructor(message = 'Could not reach the print gateway on this device.') {
+        super(message);
+        this.name = 'NetworkError';
+    }
+}
+export class JobFailedError extends PrintGatewayError {
+    constructor(jobId, lastError) {
+        super(lastError ?? `Print job ${jobId} failed`);
+        this.name = 'JobFailedError';
+        this.jobId = jobId;
+        this.lastError = lastError;
+    }
+}
+export function parseApiError(status, body) {
+    let message = body;
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed.error)
+            message = parsed.error;
+    }
+    catch {
+        // keep raw body
+    }
+    if (status === 401)
+        return new AuthError(message);
+    if (status === 429)
+        return new RateLimitError(message);
+    return new PrintGatewayError(message || `Request failed with status ${status}`, status);
+}

package/dist/fallback.d.ts

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

package/dist/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/index.d.ts

@@ -0,0 +1,35 @@
+import type { PrintDocument } from './schema.js';
+export { buildReceiptDocument } from './adapters/receiptAdapter.js';
+export type { ReceiptData, ReceiptLineItem } from './adapters/receiptAdapter.js';
+export { detectPrintGateway, isAndroidDevice } from './detect.js';
+export { detectPrintGatewayDetailed, type GatewayDetectDetailed, type GatewayDetectHint, } from './detectDetailed.js';
+export { AuthError, JobFailedError, NetworkError, PrintGatewayError, RateLimitError, } from './errors.js';
+export { fallbackWindowPrint } from './fallback.js';
+export { buildPrintIntentUrl, openPrintIntent } from './intent.js';
+export type { IntentPrintPayload } from './intent.js';
+export { PrintGatewayClient } from './print.js';
+export { createPrintRouter, parseSetupBundle, resolvePrintTarget, validateSetup, } from './setup.js';
+export type { PrintRouteOptions, PrintRouterOptions, SetupValidation } from './setup.js';
+export { textToDocument } from './textToDocument.js';
+export type { GatewayDestination, GatewayHealth, GatewayPrinter, PrintDocument, PrintDocumentBlock, PrintJobResponse, PrintOptions, PrintRequest, SetupBundle, } from './schema.js';
+export type PrintWithFallbackOptions = {
+    baseUrl?: string;
+    printerId?: string;
+    role?: string;
+    idempotencyKey?: string;
+    waitForCompletion?: boolean;
+    onlyOnAndroid?: boolean;
+    detectTimeoutMs?: number;
+};
+export type PrintResult = {
+    method: 'gateway';
+    jobId: string;
+    status: string;
+} | {
+    method: 'intent';
+    jobId: string;
+    status: string;
+} | {
+    method: 'window.print';
+};
+export declare function printWithFallback(document: PrintDocument, options?: PrintWithFallbackOptions): Promise<PrintResult>;

package/dist/index.js

@@ -0,0 +1,80 @@
+import { detectPrintGateway, isAndroidDevice } from './detect.js';
+import { fallbackWindowPrint } from './fallback.js';
+import { openPrintIntent } from './intent.js';
+import { PrintGatewayClient } from './print.js';
+import { resolvePrintTarget } from './setup.js';
+export { buildReceiptDocument } from './adapters/receiptAdapter.js';
+export { detectPrintGateway, isAndroidDevice } from './detect.js';
+export { detectPrintGatewayDetailed, } from './detectDetailed.js';
+export { AuthError, JobFailedError, NetworkError, PrintGatewayError, RateLimitError, } from './errors.js';
+export { fallbackWindowPrint } from './fallback.js';
+export { buildPrintIntentUrl, openPrintIntent } from './intent.js';
+export { PrintGatewayClient } from './print.js';
+export { createPrintRouter, parseSetupBundle, resolvePrintTarget, validateSetup, } from './setup.js';
+export { textToDocument } from './textToDocument.js';
+async function tryIntentFallback(document, target) {
+    if (!isAndroidDevice())
+        return null;
+    try {
+        openPrintIntent({
+            token: '',
+            document,
+            role: target.role,
+            printer_id: target.printerId,
+        });
+        return { method: 'intent', jobId: 'intent', status: 'submitted' };
+    }
+    catch {
+        return null;
+    }
+}
+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,
+        timeoutMs: options.detectTimeoutMs ?? 1500,
+    });
+    const client = new PrintGatewayClient({
+        baseUrl: detection.baseUrl,
+    });
+    const target = detection.available
+        ? await resolvePrintTarget(client, {
+            printerId: options.printerId,
+            role: options.role,
+            health: detection.health,
+        })
+        : {
+            printerId: options.printerId,
+            role: options.role ?? 'receipt',
+        };
+    if (!detection.available) {
+        const intentResult = await tryIntentFallback(document, target);
+        if (intentResult)
+            return intentResult;
+        await fallbackWindowPrint();
+        return { method: 'window.print' };
+    }
+    const request = {
+        document,
+        printer_id: target.printerId,
+        role: target.printerId ? undefined : target.role,
+    };
+    try {
+        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 };
+    }
+    catch {
+        const intentResult = await tryIntentFallback(document, target);
+        if (intentResult)
+            return intentResult;
+        throw new Error('Print gateway unavailable and intent fallback failed');
+    }
+}

package/dist/intent.d.ts

@@ -0,0 +1,9 @@
+import type { PrintDocument } from './schema.js';
+export type IntentPrintPayload = {
+    token: string;
+    document: PrintDocument;
+    role?: string;
+    printer_id?: string;
+};
+export declare function buildPrintIntentUrl(payload: IntentPrintPayload): string;
+export declare function openPrintIntent(payload: IntentPrintPayload): boolean;

package/dist/intent.js

@@ -0,0 +1,29 @@
+import { PrintGatewayError } from './errors.js';
+const INTENT_SCHEME = 'printgateway';
+const INTENT_PATH = 'print';
+const MAX_INTENT_PAYLOAD_BYTES = 6144;
+function base64UrlEncode(value) {
+    const bytes = new TextEncoder().encode(value);
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    const base64 = btoa(binary);
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+export function buildPrintIntentUrl(payload) {
+    const json = JSON.stringify(payload);
+    const byteLength = new TextEncoder().encode(json).byteLength;
+    if (byteLength > MAX_INTENT_PAYLOAD_BYTES) {
+        throw new PrintGatewayError(`Print payload is too large for intent fallback (${byteLength} bytes, max ${MAX_INTENT_PAYLOAD_BYTES})`);
+    }
+    const encoded = base64UrlEncode(json);
+    return `${INTENT_SCHEME}://${INTENT_PATH}?payload=${encoded}`;
+}
+export function openPrintIntent(payload) {
+    if (typeof window === 'undefined')
+        return false;
+    const url = buildPrintIntentUrl(payload);
+    window.location.href = url;
+    return true;
+}

package/dist/print.d.ts

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

package/dist/print.js

@@ -0,0 +1,89 @@
+import { AuthError, JobFailedError, NetworkError, parseApiError } from './errors.js';
+export class PrintGatewayClient {
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl ?? 'http://127.0.0.1:19643/api/v1';
+    }
+    headers(idempotencyKey) {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (idempotencyKey) {
+            headers['X-Idempotency-Key'] = idempotencyKey;
+        }
+        return headers;
+    }
+    async listPrinters() {
+        const response = await fetch(`${this.baseUrl}/printers`, {
+            headers: this.headers(),
+            credentials: 'include',
+        });
+        if (!response.ok) {
+            throw parseApiError(response.status, await response.text());
+        }
+        const payload = (await response.json());
+        return payload.printers;
+    }
+    async getHealth() {
+        try {
+            const response = await fetch(`${this.baseUrl}/health`, {
+                credentials: 'include',
+            });
+            if (!response.ok) {
+                throw parseApiError(response.status, await response.text());
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof NetworkError || error instanceof AuthError)
+                throw error;
+            throw new NetworkError(error instanceof Error ? error.message : undefined);
+        }
+    }
+    async print(request, idempotencyKey) {
+        const response = await fetch(`${this.baseUrl}/print`, {
+            method: 'POST',
+            headers: this.headers(idempotencyKey),
+            credentials: 'include',
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            throw parseApiError(response.status, await response.text());
+        }
+        return (await response.json());
+    }
+    async getJob(jobId) {
+        const response = await fetch(`${this.baseUrl}/jobs/${jobId}`, {
+            headers: this.headers(),
+            credentials: 'include',
+        });
+        if (!response.ok) {
+            throw parseApiError(response.status, await response.text());
+        }
+        return (await response.json());
+    }
+    async retryJob(jobId) {
+        const response = await fetch(`${this.baseUrl}/jobs/${jobId}/retry`, {
+            method: 'POST',
+            headers: this.headers(),
+            credentials: 'include',
+        });
+        if (!response.ok) {
+            throw parseApiError(response.status, await response.text());
+        }
+        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') {
+                return job;
+            }
+            if (job.status === 'failed') {
+                throw new JobFailedError(job.job_id, job.last_error);
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+        throw new NetworkError(`Timed out waiting for job ${jobId}`);
+    }
+}