init

lib/models/printer_exception.dart

@@ -0,0 +1,24 @@
+/// Custom exception for printer operations.
+///
+/// Encapsulates structured error information from the native layer,
+/// including error code, message, and optional details.
+class PrinterException implements Exception {
+  /// Machine-readable error code (e.g., 'INVALID_ARGUMENT', 'PORT_OPEN_FAILED').
+  final String code;
+
+  /// Human-readable error message.
+  final String message;
+
+  /// Additional error details (may be null).
+  final dynamic details;
+
+  /// Creates a [PrinterException] with the given [code] and [message].
+  const PrinterException({
+    required this.code,
+    required this.message,
+    this.details,
+  });
+
+  @override
+  String toString() => 'PrinterException($code): $message';
+}

lib/models/printer_port_handle.dart

@@ -0,0 +1,44 @@
+/// Close callback type for [PrinterPortHandle].
+typedef ClosePortCallback = Future<bool> Function(int handle);
+
+/// Represents an open printer port handle.
+///
+/// Wraps an integer handle and provides a [close] method to release
+/// the underlying native port resource. Once closed, the handle
+/// becomes invalid.
+class PrinterPortHandle {
+  /// The integer handle returned by the native layer.
+  final int handle;
+
+  /// Callback to close the port. If null, close() is a no-op.
+  final ClosePortCallback? _closeCallback;
+
+  /// Whether the port is still valid (not closed).
+  bool _isValid;
+
+  /// Creates a [PrinterPortHandle] with the given [handle] and optional [closeCallback].
+  PrinterPortHandle({
+    required this.handle,
+    ClosePortCallback? closeCallback,
+  })  : _closeCallback = closeCallback,
+        _isValid = true;
+
+  /// Returns true if the port is still open and not closed.
+  bool get isValid => _isValid;
+
+  /// Closes the port and marks the handle as invalid.
+  ///
+  /// Subsequent calls to [close] are no-ops if the port is already closed.
+  Future<void> close() async {
+    if (!_isValid) {
+      return;
+    }
+    _isValid = false;
+    if (_closeCallback != null) {
+      await _closeCallback(handle);
+    }
+  }
+
+  @override
+  String toString() => 'PrinterPortHandle(handle: $handle, valid: $_isValid)';
+}