Shared Library

The lib/ package contains shared TypeScript modules used by both the server and web frontend. It provides common functionality for schemas, database, HTTP, MQTT, JWT, and type definitions.

Structure

lib/src/
├── schemas.ts      # Valibot schemas for MQTT, KISS, LLD, WebSocket
├── generic.ts      # Shared utilities (beacon validation, JSON, dev mode)
├── db.ts           # SQLite initialization and migrations
├── http.ts         # Bun HTTP server and WebSocket setup
├── mqtt.ts         # MQTT client for beacon/gateway data
├── jose.ts         # JWT key creation, signing, verification
├── rs.ts           # HTTP response helpers (401, 403, 400, CORS)
├── server.ts       # Server-specific response helpers
├── client.ts       # Frontend-specific assertion helpers
├── ip.ts           # IP validation and subnet utilities
├── kiss.ts         # KISS API integration
├── zabbix.ts       # Zabbix sender for monitoring
├── beacon.ts       # Beacon UUID validation and Zabbix hostname
├── perf.ts         # Performance logging
├── log.ts          # Database logging
└── types/          # TypeScript type definitions
    ├── query.d.ts  # Database query result types
    ├── db.d.ts     # Database types
    ├── http.d.ts   # HTTP/WebSocket types
    ├── mqtt.d.ts   # MQTT message types
    ├── jose.d.ts   # JWT key types
    ├── rs.d.ts     # Response types
    ├── generic.d.ts # Generic utility types
    ├── zone.d.ts   # Zone types
    ├── beacon.d.ts # Beacon types
    ├── pixi.d.ts   # Pixi.js types (for web)
    ├── lld.d.ts    # Zabbix LLD types
    ├── cache_bridge.d.ts # Cache/bridge types
    ├── zabbix.d.ts # Zabbix types
    ├── kiss.d.ts   # KISS API types
    ├── enums.ts    # Shared enumerations
    └── rq.d.ts     # Request types

Usage

The server imports lib/ modules using relative paths:

import { db_start } from "../../lib/src/db";
import { MqttButtonAdv1Schema } from "../../lib/src/schemas";
import type { QueryResultBeacon } from "../../lib/src/types/query";

The web frontend uses its own internal web/src/lib/ directory and does not directly import from lib/. However, it shares the same Valibot schema patterns.

Dependencies

Package	Version	Purpose
jose	^6.0.10	JWT signing and verification
mqtt	^5.13.1	MQTT broker client
pixi.js	^8.10.1	Types for web canvas
valibot	^1.1.0	Runtime schema validation

Development

cd lib

# Install dependencies
bun install

# Type checking
bun run typecheck