@savepoint/bridge 1.0.0

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import pc from 'picocolors';
+const VERSION = '1.0.0';
+const [, , command, ...args] = process.argv;
+const COMMANDS = {
+    setup: 'Interactive guided setup wizard',
+    start: 'Start the bridge daemon (without installing as a service)',
+    status: 'Show running state, connected printers, recent jobs',
+    logs: 'Tail the local log file',
+    discover: 'Scan for printers on your network and local CUPS queues',
+    uninstall: 'Remove OS service and stored token',
+};
+function printHelp() {
+    console.log(pc.bold(`\nSavePoint Bridge  v${VERSION}`));
+    console.log('Local hardware connector for SavePoint\n');
+    console.log(pc.bold('Commands:'));
+    for (const [cmd, desc] of Object.entries(COMMANDS)) {
+        console.log(`  ${pc.cyan(cmd.padEnd(12))} ${desc}`);
+    }
+    console.log('\nOptions:');
+    console.log('  --token=<token>       Skip token prompt in setup');
+    console.log('  --non-interactive     Skip all prompts, use defaults');
+    console.log('  --no-service          Do not install as OS service');
+    console.log('  --log-level=debug     Verbose output');
+    console.log();
+}
+async function main() {
+    switch (command) {
+        case 'setup': {
+            const { runSetup } = await import('./setup.js');
+            await runSetup(args);
+            break;
+        }
+        case 'start': {
+            const { runDaemon } = await import('./daemon.js');
+            await runDaemon();
+            break;
+        }
+        case 'status':
+            {
+                const { showStatus } = await import('./status.js');
+                await showStatus();
+            }
+            break;
+        case 'logs':
+            {
+                const { showLogs } = await import('./logs.js');
+                showLogs();
+            }
+            break;
+        case 'discover': {
+            const { discoverPrinters } = await import('./discovery.js');
+            const found = await discoverPrinters();
+            console.log(JSON.stringify(found, null, 2));
+            break;
+        }
+        case 'uninstall': {
+            const { uninstallService } = await import('./service.js');
+            await uninstallService();
+            break;
+        }
+        case '--version':
+        case 'version':
+            console.log(VERSION);
+            break;
+        default:
+            printHelp();
+    }
+}
+main().catch(err => {
+    console.error(pc.red('Fatal:'), err.message);
+    process.exit(1);
+});

package/dist/daemon.d.ts

@@ -0,0 +1,10 @@
+interface IntervalConfig {
+    activeMs: number;
+    idleMs: number;
+    idleAfter: number;
+}
+export declare function buildIntervalStrategy(config: IntervalConfig): {
+    next(hadJobs: boolean): number;
+};
+export declare function runDaemon(): Promise<void>;
+export {};

package/dist/daemon.js

@@ -0,0 +1,141 @@
+import { log } from './logger.js';
+import { loadToken } from './token.js';
+import { Poller } from './poller.js';
+import { Registry } from './registry.js';
+import { getTransport } from './printer.js';
+import { discoverPrinters } from './discovery.js';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { DATA_PATH } from './logger.js';
+const BASE_URL = process.env.SAVEPOINT_API_URL ?? 'https://api.savepointhq.com';
+const VERSION = '1.0.0';
+const DB_PATH = join(DATA_PATH, 'registry.db');
+const CAPS_PATH = fileURLToPath(new URL('../../capabilities/printers.json', import.meta.url));
+const REGISTRY_REFRESH_MS = 5 * 60 * 1000;
+const HEARTBEAT_MS = 60 * 1000;
+export function buildIntervalStrategy(config) {
+    let emptyCount = 0;
+    return {
+        next(hadJobs) {
+            if (hadJobs) {
+                emptyCount = 0;
+                return config.activeMs;
+            }
+            emptyCount++;
+            return emptyCount >= config.idleAfter ? config.idleMs : config.activeMs;
+        }
+    };
+}
+export async function runDaemon() {
+    const token = await loadToken();
+    if (!token) {
+        log.notice('No agent token found. Run: savepoint-bridge setup');
+        process.exit(1);
+    }
+    const poller = new Poller({ baseUrl: BASE_URL, token, version: VERSION });
+    const registry = new Registry(DB_PATH);
+    registry.init();
+    registry.seedCapabilities(CAPS_PATH);
+    log.success('SavePoint Bridge started');
+    await syncDiscoveredPrinters(poller);
+    await refreshRegistry(poller, registry);
+    setInterval(() => refreshRegistry(poller, registry), REGISTRY_REFRESH_MS);
+    setInterval(() => poller.heartbeat(), HEARTBEAT_MS);
+    setInterval(() => syncDiscoveredPrinters(poller), REGISTRY_REFRESH_MS);
+    const strategy = buildIntervalStrategy({ activeMs: 5_000, idleMs: 30_000, idleAfter: 3 });
+    async function tick() {
+        let hadJobs = false;
+        try {
+            const jobs = await poller.pollJobs();
+            hadJobs = jobs.length > 0;
+            for (const job of jobs) {
+                await processJob(job, poller, registry);
+            }
+        }
+        catch (e) {
+            if (e instanceof Error && e.message === 'UNAUTHORIZED') {
+                log.notice('Bridge token revoked. Run: savepoint-bridge setup');
+                process.exit(1);
+            }
+            log.error('Poll error', e);
+        }
+        setTimeout(tick, strategy.next(hadJobs));
+    }
+    tick();
+    for (const sig of ['SIGINT', 'SIGTERM']) {
+        process.on(sig, () => { log.info('Shutting down...'); registry.close(); process.exit(0); });
+    }
+}
+async function refreshRegistry(poller, registry) {
+    try {
+        const printers = await poller.fetchPrinters();
+        registry.upsertPrinters(printers);
+    }
+    catch (e) {
+        log.warn('Registry refresh failed', e);
+    }
+}
+async function syncDiscoveredPrinters(poller) {
+    try {
+        const printers = await discoverPrinters();
+        await poller.heartbeat(printers);
+    }
+    catch (e) {
+        log.warn('Printer discovery sync failed', e);
+    }
+}
+async function processJob(job, poller, registry) {
+    log.info(`Processing job ${job.id} (${job.job_type})`);
+    const claimed = await poller.claimJob(job.id);
+    if (!claimed) {
+        log.info(`Job ${job.id} already claimed — skipping`);
+        return;
+    }
+    try {
+        const format = job.metadata?.format;
+        if (job.printer_id && format) {
+            const err = registry.validateFormat(job.printer_id, format);
+            if (err) {
+                await poller.reportResult(job.id, 'failed', { code: err.code, message: err.message });
+                log.warn(`Job ${job.id} failed validation: ${err.message}`);
+                return;
+            }
+        }
+        if (!job.content_url) {
+            await poller.reportResult(job.id, 'failed', { code: 'NO_CONTENT_URL' });
+            return;
+        }
+        const bytes = await downloadWithRetry(job.content_url);
+        const printer = job.printer_id ? registry.getPrinter(job.printer_id) : null;
+        if (!printer) {
+            await poller.reportResult(job.id, 'failed', { code: 'PRINTER_NOT_FOUND' });
+            return;
+        }
+        const transport = getTransport(printer);
+        await transport.send(bytes);
+        await poller.reportResult(job.id, 'completed', { code: 'OK' });
+        log.success(`Job ${job.id} completed`);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        await poller.reportResult(job.id, 'failed', { code: 'DISPATCH_ERROR', message });
+        log.error(`Job ${job.id} failed: ${message}`);
+    }
+}
+async function downloadWithRetry(url, retries = 3) {
+    let lastErr;
+    for (let i = 0; i < retries; i++) {
+        try {
+            const res = await fetch(url);
+            if (!res.ok)
+                throw new Error(`DOWNLOAD_FAILED: HTTP ${res.status}`);
+            return Buffer.from(await res.arrayBuffer());
+        }
+        catch (e) {
+            lastErr = e;
+            if (i < retries - 1)
+                await new Promise(r => setTimeout(r, 2_000 * Math.pow(3, i)));
+        }
+    }
+    throw lastErr;
+}

package/dist/discovery.d.ts

@@ -0,0 +1,8 @@
+export interface DiscoveredPrinter {
+    name: string;
+    host?: string;
+    port?: number;
+    connection_type: 'network' | 'usb' | 'system';
+    model?: string;
+}
+export declare function discoverPrinters(): Promise<DiscoveredPrinter[]>;

package/dist/discovery.js

@@ -0,0 +1,54 @@
+import { createConnection } from 'net';
+import { networkInterfaces } from 'os';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+function probePort(host, port, timeoutMs = 1500) {
+    return new Promise(resolve => {
+        const socket = createConnection({ host, port });
+        const timer = setTimeout(() => { socket.destroy(); resolve(false); }, timeoutMs);
+        socket.on('connect', () => { clearTimeout(timer); socket.end(); resolve(true); });
+        socket.on('error', () => { clearTimeout(timer); resolve(false); });
+    });
+}
+function getSubnetHosts() {
+    const nets = networkInterfaces();
+    for (const ifaces of Object.values(nets)) {
+        for (const iface of ifaces ?? []) {
+            if (iface.family === 'IPv4' && !iface.internal) {
+                const prefix = iface.address.split('.').slice(0, 3).join('.');
+                return Array.from({ length: 254 }, (_, i) => `${prefix}.${i + 1}`);
+            }
+        }
+    }
+    return [];
+}
+async function scanNetwork(concurrency = 50) {
+    const hosts = getSubnetHosts();
+    const found = [];
+    for (let i = 0; i < hosts.length; i += concurrency) {
+        await Promise.allSettled(hosts.slice(i, i + concurrency).map(async (host) => {
+            if (await probePort(host, 9100)) {
+                found.push({ name: host, host, port: 9100, connection_type: 'network' });
+            }
+        }));
+    }
+    return found;
+}
+/** Enumerate CUPS system printers (macOS/Linux) using execFile — no shell injection */
+async function scanCups() {
+    try {
+        const { stdout } = await execFileAsync('lpstat', ['-p']);
+        return stdout
+            .split('\n')
+            .filter(line => line.startsWith('printer '))
+            .map(line => ({ name: line.split(' ')[1], connection_type: 'system' }));
+    }
+    catch {
+        return []; // lpstat unavailable (Windows or CUPS not installed)
+    }
+}
+export async function discoverPrinters() {
+    const [network, cups] = await Promise.all([scanNetwork(), scanCups()]);
+    return [...network, ...cups];
+}

package/dist/logger.d.ts

@@ -0,0 +1,9 @@
+export declare const log: {
+    info: (msg: string, data?: unknown) => void;
+    success: (msg: string, data?: unknown) => void;
+    warn: (msg: string, data?: unknown) => void;
+    error: (msg: string, data?: unknown) => void;
+    /** Prominent notice — always visible */
+    notice: (msg: string) => void;
+};
+export declare const DATA_PATH: string;

package/dist/logger.js

@@ -0,0 +1,59 @@
+import pc from 'picocolors';
+import { appendFileSync, mkdirSync, readdirSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+const DATA_DIR = process.env.SAVEPOINT_BRIDGE_DATA_PATH || join(homedir(), '.savepoint-bridge');
+const LOG_DIR = join(DATA_DIR, 'logs');
+const MAX_LOG_DAYS = 7;
+function logFilePath() {
+    const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    return join(LOG_DIR, `${date}.log`);
+}
+function writeToFile(level, message, data) {
+    try {
+        mkdirSync(LOG_DIR, { recursive: true });
+        pruneOldLogs();
+        const line = JSON.stringify({ ts: new Date().toISOString(), level, message, data }) + '\n';
+        appendFileSync(logFilePath(), line, 'utf8');
+    }
+    catch {
+        // log file write failure is non-fatal
+    }
+}
+function pruneOldLogs() {
+    const cutoff = Date.now() - MAX_LOG_DAYS * 24 * 60 * 60 * 1000;
+    for (const file of readdirSync(LOG_DIR)) {
+        if (!file.endsWith('.log'))
+            continue;
+        const date = new Date(file.slice(0, 10));
+        if (Number.isNaN(date.getTime()))
+            continue;
+        if (date.getTime() < cutoff) {
+            rmSync(join(LOG_DIR, file), { force: true });
+        }
+    }
+}
+export const log = {
+    info: (msg, data) => {
+        console.log(pc.cyan('ℹ'), msg);
+        writeToFile('info', msg, data);
+    },
+    success: (msg, data) => {
+        console.log(pc.green('✔'), msg);
+        writeToFile('info', msg, data);
+    },
+    warn: (msg, data) => {
+        console.warn(pc.yellow('⚠'), msg);
+        writeToFile('warn', msg, data);
+    },
+    error: (msg, data) => {
+        console.error(pc.red('✖'), msg);
+        writeToFile('error', msg, data);
+    },
+    /** Prominent notice — always visible */
+    notice: (msg) => {
+        console.log(pc.bold(pc.yellow('\n' + msg + '\n')));
+        writeToFile('notice', msg);
+    },
+};
+export const DATA_PATH = DATA_DIR;

package/dist/logs.d.ts

@@ -0,0 +1 @@
+export declare function showLogs(limit?: number): void;

package/dist/logs.js

@@ -0,0 +1,30 @@
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { DATA_PATH } from './logger.js';
+function getRecentLogFiles(limit = 2) {
+    const logDir = join(DATA_PATH, 'logs');
+    if (!existsSync(logDir))
+        return [];
+    return readdirSync(logDir)
+        .filter((file) => file.endsWith('.log'))
+        .sort()
+        .slice(-limit)
+        .map((file) => join(logDir, file));
+}
+export function showLogs(limit = 50) {
+    const files = getRecentLogFiles();
+    if (files.length === 0) {
+        console.log('No log files found.');
+        return;
+    }
+    const entries = files.flatMap((file) => readFileSync(file, 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => JSON.parse(line)));
+    const recent = entries.slice(-limit);
+    for (const entry of recent) {
+        const ts = entry.ts.replace('T', ' ').replace('Z', ' UTC');
+        const suffix = entry.data ? ` ${JSON.stringify(entry.data)}` : '';
+        console.log(`[${ts}] ${entry.level.toUpperCase()} ${entry.message}${suffix}`);
+    }
+}

package/dist/poller.d.ts

@@ -0,0 +1,19 @@
+import type { JobResult, PrintJob } from './types.js';
+import type { DiscoveredPrinter } from './discovery.js';
+export interface PollerConfig {
+    baseUrl: string;
+    token: string;
+    version: string;
+}
+export declare class Poller {
+    private config;
+    private headers;
+    constructor(config: PollerConfig);
+    private request;
+    pollJobs(): Promise<PrintJob[]>;
+    /** Returns the claimed job, or null if already claimed by another instance (409) */
+    claimJob(jobId: string): Promise<PrintJob | null>;
+    reportResult(jobId: string, status: 'completed' | 'failed', result: JobResult): Promise<void>;
+    heartbeat(printers?: DiscoveredPrinter[]): Promise<void>;
+    fetchPrinters(): Promise<unknown[]>;
+}

package/dist/poller.js

@@ -0,0 +1,70 @@
+export class Poller {
+    config;
+    headers;
+    constructor(config) {
+        this.config = config;
+        this.headers = {
+            'Authorization': `Bearer ${config.token}`,
+            'X-Agent-Version': config.version,
+            'Content-Type': 'application/json',
+        };
+    }
+    async request(path, init) {
+        const res = await fetch(`${this.config.baseUrl}${path}`, {
+            ...init,
+            headers: { ...this.headers, ...init?.headers },
+        });
+        if (res.status === 401)
+            throw new Error('UNAUTHORIZED');
+        return res;
+    }
+    async pollJobs() {
+        const res = await this.request('/api/labels/print-jobs');
+        if (res.status === 204)
+            return [];
+        const { job } = await res.json();
+        return job ? [job] : [];
+    }
+    /** Returns the claimed job, or null if already claimed by another instance (409) */
+    async claimJob(jobId) {
+        const res = await this.request(`/api/labels/print-jobs/${jobId}/claim`, {
+            method: 'POST',
+        });
+        if (res.status === 409)
+            return null;
+        if (!res.ok)
+            throw new Error(`Claim failed: ${res.status}`);
+        const { job } = await res.json();
+        return job;
+    }
+    async reportResult(jobId, status, result) {
+        await this.request(`/api/labels/print-jobs/${jobId}/result`, {
+            method: 'POST',
+            body: JSON.stringify({ status, result }),
+        });
+    }
+    async heartbeat(printers) {
+        try {
+            await this.request('/api/agents/heartbeat', {
+                method: 'POST',
+                body: JSON.stringify({
+                    version: this.config.version,
+                    printers: printers?.map((printer) => ({
+                        name: printer.name,
+                        host: printer.host ?? null,
+                        port: printer.port ?? null,
+                        connection_type: printer.connection_type === 'system' ? 'cups' : printer.connection_type,
+                    })),
+                }),
+            });
+        }
+        catch {
+            // heartbeat failure is non-fatal — daemon continues
+        }
+    }
+    async fetchPrinters() {
+        const res = await this.request('/api/agents/printers');
+        const { printers } = await res.json();
+        return printers ?? [];
+    }
+}

package/dist/printer.d.ts

@@ -0,0 +1,18 @@
+interface Transport {
+    send(bytes: Buffer): Promise<void>;
+}
+interface NetworkOptions {
+    timeoutMs?: number;
+    retries?: number;
+}
+export declare function createNetworkTransport(host: string, port: number, opts?: NetworkOptions): Transport;
+/** CUPS transport — uses execFile (not exec) to prevent shell injection */
+export declare function createCupsTransport(printerName: string): Transport;
+export declare function createUsbTransport(_devicePath: string): Transport;
+export declare function getTransport(printer: {
+    connectionType: string;
+    host: string | null;
+    port: number | null;
+    model?: string | null;
+}): Transport;
+export {};

package/dist/printer.js

@@ -0,0 +1,82 @@
+import { createConnection } from 'net';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+export function createNetworkTransport(host, port, opts = {}) {
+    const { timeoutMs = 10_000, retries = 3 } = opts;
+    async function attempt(bytes) {
+        return new Promise((resolve, reject) => {
+            const socket = createConnection({ host, port });
+            const timer = setTimeout(() => {
+                socket.destroy();
+                reject(new Error(`Connection to ${host}:${port} timed out`));
+            }, timeoutMs);
+            socket.once('error', (err) => { clearTimeout(timer); socket.destroy(); reject(err); });
+            socket.on('connect', () => {
+                socket.write(bytes, 'binary', (err) => {
+                    clearTimeout(timer);
+                    socket.end();
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        });
+    }
+    return {
+        async send(bytes) {
+            let lastErr;
+            for (let i = 0; i < retries; i++) {
+                try {
+                    await attempt(bytes);
+                    return;
+                }
+                catch (e) {
+                    lastErr = e;
+                    if (i < retries - 1)
+                        await new Promise(r => setTimeout(r, 1000 * Math.pow(3, i)));
+                }
+            }
+            throw new Error(`CONNECTION_FAILED after ${retries} attempts: ${lastErr?.message}`);
+        }
+    };
+}
+/** CUPS transport — uses execFile (not exec) to prevent shell injection */
+export function createCupsTransport(printerName) {
+    return {
+        async send(bytes) {
+            // lpr args are passed as an array — no shell interpolation
+            const { execFile: ef } = await import('child_process');
+            await new Promise((resolve, reject) => {
+                // printerName comes from our own registry, but still use execFile for safety
+                const proc = ef('lpr', ['-P', printerName], (err) => err ? reject(err) : resolve());
+                proc.stdin?.write(bytes);
+                proc.stdin?.end();
+            });
+        }
+    };
+}
+export function createUsbTransport(_devicePath) {
+    return {
+        async send(_bytes) {
+            // USB implementation requires device enumeration from discovery module.
+            // Full implementation is a v1.1 task — covered under Windows Zadig notes in spec.
+            throw new Error('USB transport not yet implemented — use network or CUPS connection type');
+        }
+    };
+}
+export function getTransport(printer) {
+    if (printer.connectionType === 'network') {
+        if (!printer.host || !printer.port)
+            throw new Error('Network printer missing host or port');
+        return createNetworkTransport(printer.host, printer.port);
+    }
+    if (printer.connectionType === 'system') {
+        return createCupsTransport(printer.host ?? printer.model ?? 'default');
+    }
+    if (printer.connectionType === 'usb') {
+        return createUsbTransport(printer.host ?? '');
+    }
+    throw new Error(`Unsupported connection type: ${printer.connectionType}`);
+}

package/dist/registry.d.ts

@@ -0,0 +1,17 @@
+import type { Printer } from './types.js';
+export interface RegistryError {
+    code: 'FORMAT_MISMATCH' | 'PRINTER_NOT_FOUND';
+    message: string;
+}
+export declare class Registry {
+    private db;
+    constructor(dbPath: string);
+    init(): void;
+    seedCapabilities(jsonPath: string): void;
+    upsertPrinters(printers: Printer[]): void;
+    getPrinter(id: string): Printer | null;
+    getExpectedFormat(printerId: string): string | null;
+    validateFormat(printerId: string, jobFormat: string): RegistryError | null;
+    close(): void;
+    listPrinters(): Printer[];
+}