Printer Status API

This document describes printer status workflows: start/stop, operational flags, drawer control, on-demand reads, and streaming.

Notes:

• JSON responses omit null fields globally.
• Drawer state "OpenedByCommand" is emitted by ESC/POS pulses and cannot be set via API.

Types (TypeScript)

type PrinterTargetState = "Started" | "Stopped";

type PrinterListenerState = "Starting" | "Started" | "Stopped" | "Error";

type DrawerState = "Closed" | "OpenedManually" | "OpenedByCommand";

type PrinterDto = { id: string; displayName: string; isPinned: boolean; lastViewedDocumentId: string | null; lastDocumentReceivedAt: string | null; };

type PrinterSettingsDto = { protocol: "EscPos"; widthInDots: number; heightInDots: number | null; tcpListenPort: number; emulateBufferCapacity: boolean; bufferDrainRate: number | null; bufferMaxCapacity: number | null; };

type PrinterOperationalFlagsDto = { printerId: string; targetState: PrinterTargetState; updatedAt: string; isCoverOpen: boolean; isPaperOut: boolean; isOffline: boolean; hasError: boolean; isPaperNearEnd: boolean; };

type PrinterRuntimeStatusDto = { printerId: string; state: PrinterListenerState; updatedAt: string; bufferedBytes: number | null; drawer1State: DrawerState | null; drawer2State: DrawerState | null; };

type PrinterResponseDto = { printer: PrinterDto; settings: PrinterSettingsDto; operationalFlags: PrinterOperationalFlagsDto | null; runtimeStatus: PrinterRuntimeStatusDto | null; };

type PrinterSidebarSnapshotDto = { printer: PrinterDto; runtimeStatus?: PrinterRuntimeStatusDto; };

type PrinterRuntimeStatusUpdateDto = { state?: PrinterListenerState; updatedAt: string; bufferedBytes?: number | null; drawer1State?: DrawerState | null; drawer2State?: DrawerState | null; };

type PrinterOperationalFlagsUpdateDto = { printerId: string; updatedAt: string; targetState?: PrinterTargetState; isCoverOpen?: boolean; isPaperOut?: boolean; isOffline?: boolean; hasError?: boolean; isPaperNearEnd?: boolean; };

type PrinterStatusUpdateDto = { printerId: string; updatedAt: string; runtime?: PrinterRuntimeStatusUpdateDto; operationalFlags?: PrinterOperationalFlagsUpdateDto; settings?: PrinterSettingsDto; printer?: PrinterDto; };

Requests

type CreatePrinterRequestDto = { printer: { id: string; displayName: string }; settings: { protocol: "EscPos"; widthInDots: number; heightInDots: number | null; emulateBufferCapacity: boolean; bufferDrainRate: number | null; bufferMaxCapacity: number | null; }; };

type UpdatePrinterRequestDto = { printer: { id: string; displayName: string }; settings: { protocol: "EscPos"; widthInDots: number; heightInDots: number | null; emulateBufferCapacity: boolean; bufferDrainRate: number | null; bufferMaxCapacity: number | null; }; };

type UpdatePrinterOperationalFlagsRequestDto = { isCoverOpen?: boolean; isPaperOut?: boolean; isOffline?: boolean; hasError?: boolean; isPaperNearEnd?: boolean; targetState?: PrinterTargetState; };

type UpdatePrinterDrawerStateRequestDto = { drawer1State?: "Closed" | "OpenedManually"; drawer2State?: "Closed" | "OpenedManually"; };

Endpoints

POST /api/printers

Creates a printer.

Response: PrinterResponseDto

PUT /api/printers/

Updates printer metadata and settings.

Response: PrinterResponseDto

GET /api/printers

Lists full printer snapshots.

Response: PrinterResponseDto[]

GET /api/printers/

Reads a full printer snapshot.

Response: PrinterResponseDto

PATCH /api/printers/

Partial update of operational flags. Setting targetState starts or stops the printer listener.

Response: PrinterOperationalFlagsDto

PATCH /api/printers/

Manual drawer open/close (OpenedByCommand cannot be set via API).

Response: PrinterRuntimeStatusDto

Streaming

GET /api/printers/sidebar

Returns sidebar snapshots (metadata + state-only runtime).

Response: PrinterSidebarSnapshotDto[]

GET /api/printers/sidebar/stream

Server-sent events for sidebar updates.

Event: sidebar Payload: PrinterSidebarSnapshotDto

GET /api/printers/

Server-sent events for active printer updates. Payload is partial; only changed sections are present (runtime/operationalFlags/settings/printer).

Event: status Payload: PrinterStatusUpdateDto

Error Responses

Errors use ProblemDetails-like JSON:

type ProblemDetails = { status: number; detail: string; instance: string; };