1.0.0

Author: philptr

.gitignore

@@ -0,0 +1,3 @@
+/.swiftpm/xcode/package.xcworkspace/xcuserdata/phil.xcuserdatad/UserInterfaceState.xcuserstate
+.DS_Store
+.swiftpm

Package.resolved

@@ -0,0 +1,31 @@
+// swift-tools-version: 6.0
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "EventTapCore",
+    platforms: [
+        .macOS("11.0"),
+    ],
+    products: [
+        // Products define the executables and libraries a package produces, making them visible to other packages.
+        .library(
+            name: "EventTapCore",
+            targets: ["EventTapCore"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-async-algorithms", from: "1.0.0"),
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package, defining a module or a test suite.
+        // Targets can depend on other targets in this package and products from dependencies.
+        .target(
+            name: "EventTapCore",
+            dependencies: [
+                .product(name: "AsyncAlgorithms", package: "swift-async-algorithms"),
+            ]
+        ),
+
+    ]
+)

Package.swift

@@ -1,2 +1,124 @@
 # EventTapCore
-Swift wrapper around CGEvent and the Event Tap set of APIs.
+
+EventTapCore is a Swift module that provides a wrapper around `CGEvent` and related types, as well as a high-level, type-safe interface for monitoring and handling system events on macOS. It wraps the low-level Core Graphics event tap APIs in a modern, Swift-friendly way with support for async streams and a SwiftUI integration.
+
+## Features
+
+- Rich event metadata and field information
+- Type-safe event monitoring with async/await support
+- SwiftUI-ready with `@Observable` integration
+
+## Installation
+
+### Swift Package Manager
+
+Add the following to your `Package.swift` file:
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/philptr/EventTapCore.git", from: "1.0.0")
+]
+```
+
+## Basic Usage
+
+### Simple Event Monitoring
+
+```swift
+import EventTapCore
+
+let tap = EventTap(tapLocation: .session, tapPlacement: .head)
+
+try tap.startMonitoring { type, event in
+    print("Received event of type \(type): \(event).")
+}
+```
+
+### Using Async Streams
+
+```swift
+import EventTapCore
+
+let eventStream = EventTap.events(at: .session, placement: .head)
+
+for await event in eventStream {
+    print("Received event: \(event).")
+}
+```
+
+### SwiftUI Integration with EventTapCoordinator
+
+```swift
+import EventTapCore
+
+@main
+struct MyApp: App {
+    @State private var coordinator = EventTapCoordinator()
+    
+    var body: some Scene {
+        WindowGroup {
+            EventList(events: coordinator.events)
+                .onAppear {
+                    coordinator.startMonitoring()
+                }
+        }
+    }
+}
+```
+
+## Interface
+
+### `EventTap`
+
+The primary class for creating and managing event taps, as well as receiving callbacks. It provides both closure-based and async stream APIs for event monitoring.
+
+### `EventTapCoordinator`
+
+A higher level, SwiftUI-friendly coordinator that manages event monitoring and state, providing:
+- Observable event collection;
+- Automatic event throttling;
+- Thread-safe event handling;
+- Lifecycle management.
+
+### Event
+
+A structure that represents a system event with rich metadata including timestamp, location, event type, and associated field values.
+
+## Security and Permissions
+
+EventTapCore requires Input Monitoring permissions to monitor events from other applications. This requirement is imposed by the low-level API. In your application, you might want to include an experience to allow the user to grant your application access.
+
+```swift
+// Check if we have permission to monitor events.
+if CGPreflightListenEventAccess() {
+    // Start monitoring...
+} else {
+    // Request permission.
+    CGRequestListenEventAccess()
+    
+    // Offer to take the user to System Settings...
+}
+```
+
+## Best Practices
+
+1. Always handle tap lifecycle properly:
+   ```swift
+   // Start monitoring when needed
+   try tap.startMonitoring(...)
+   
+   // Stop monitoring when done
+   tap.stopMonitoring()
+   ```
+
+2. Consider event throttling, especially when displaying events in the UI or altering state:
+   ```swift
+   coordinator.startMonitoring(throttledFor: .milliseconds(500))
+   ```
+
+3. Check for Input Monitoring permissions before starting.
+
+## Requirements
+
+- macOS 11.0 or later
+- Swift 6.0 or later

README.md

@@ -0,0 +1,147 @@
+//
+//  Event.swift
+//  EventTapper
+//
+//  Created by Phil Zakharchenko on 2/23/24.
+//
+
+import AppKit
+
+/// A structure that represents a system event with its associated metadata and properties.
+/// Events can represent various user interactions such as keyboard input, mouse movements,
+/// and gesture recognition.
+public struct Event: Hashable, Sendable {
+    /// A field containing an integer value associated with an event.
+    /// Used for properties like key codes, click counts, and other discrete measurements.
+    public struct IntField: EventField {
+        /// The key identifying what this field represents.
+        public let key: EventFieldKey
+        
+        /// The integer value associated with this field.
+        public let value: Int64
+    }
+    
+    /// A field containing a floating-point value associated with an event.
+    /// Used for properties like mouse deltas, gesture scales, and other continuous measurements.
+    public struct DoubleField: EventField {
+        /// The key identifying what this field represents.
+        public let key: EventFieldKey
+        
+        /// The floating-point value associated with this field.
+        public let value: Double
+    }
+    
+    /// The raw Quartz timestamp of when the event occurred.
+    /// Measured in nanoseconds since system startup.
+    public let rawTimestamp: CGEventTimestamp
+    
+    /// The date when the event occurred, converted from the raw timestamp.
+    public let date: Date
+    
+    /// The type of event (e.g., mouse click, key press, gesture).
+    public let type: EventTypeKey
+    
+    /// The mouse cursor location in screen coordinates.
+    /// Origin is at the bottom-left corner of the primary screen.
+    public let mouseLocation: CGPoint
+    
+    /// The mouse cursor location with Y-coordinate unflipped.
+    /// Origin is at the top-left corner of the primary screen.
+    public let unflippedLocation: CGPoint
+    
+    /// The Unicode character associated with a keyboard event, if any.
+    /// This will be nil for non-keyboard events or special keys.
+    public let keyboardKey: UniChar?
+    
+    /// A string representation of the keyboard character, if available.
+    /// This will be nil for non-keyboard events or special keys.
+    public let keyboardKeyString: String?
+    
+    /// The set of modifier flags active during the event.
+    public let flags: Set<EventFlag>
+    
+    /// Additional integer-valued fields associated with the event.
+    /// These vary based on the event type and may include things like:
+    /// - Mouse click count.
+    /// - Keyboard repeat count.
+    /// - Process IDs.
+    public let intFields: [IntField]
+    
+    /// Additional floating-point fields associated with the event.
+    /// These vary based on the event type and may include things like:
+    /// - Scroll wheel deltas.
+    /// - Gesture scales.
+    /// - Mouse movement deltas.
+    public let doubleFields: [DoubleField]
+    
+    /// Creates a new `Event` instance from a CoreGraphics event and its type.
+    ///
+    /// This initializer processes the raw `CGEvent` to extract all relevant information
+    /// and store it in a more accessible format.
+    ///
+    /// - Parameters:
+    ///   - event: The CoreGraphics event to process
+    ///   - eventType: The type of the event
+    public init(event: CGEvent, of eventType: CGEventType) {
+        rawTimestamp = event.timestamp
+        
+        // Convert the timestamp to a Date for easier handling.
+        let eventTime = TimeInterval(Double(rawTimestamp) / 10e8)
+        date = Date(timeInterval: eventTime, since: .systemStartup)
+        
+        // Store basic event properties.
+        type = EventTypeKey(rawValue: eventType.rawValue)
+        mouseLocation = event.location
+        unflippedLocation = event.unflippedLocation
+        flags = event.flags.eventFlagSet
+        
+        // Extract keyboard character if present.
+        var char = UniChar()
+        var length = 0
+        event.keyboardGetUnicodeString(maxStringLength: 1, actualStringLength: &length, unicodeString: &char)
+        
+        if char != 0 {
+            keyboardKey = char
+            
+            if keyboardKey != 0, let scalar = UnicodeScalar(char) {
+                keyboardKeyString = String(Character(scalar))
+            } else {
+                keyboardKeyString = nil
+            }
+        } else {
+            keyboardKey = nil
+            keyboardKeyString = nil
+        }
+        
+        // Extract additional event fields.
+        var intFields: [IntField] = []
+        var doubleFields: [DoubleField] = []
+        
+        // Check all possible field indices.
+        // The range 0..<200 covers all currently defined CGEventFields.
+        (0..<200).forEach { fieldIndex in
+            let rawValue = UInt32(fieldIndex)
+            guard let field = CGEventField(rawValue: rawValue) else { return }
+            
+            // Try to get both integer and double values.
+            let intValue = event.getIntegerValueField(field)
+            let doubleValue = event.getDoubleValueField(field)
+            
+            // Store non-zero values in appropriate arrays.
+            if intValue != 0 {
+                intFields.append(.init(key: EventFieldKey(rawValue: rawValue), value: intValue))
+            } else if doubleValue != 0 {
+                doubleFields.append(.init(key: EventFieldKey(rawValue: rawValue), value: doubleValue))
+            }
+        }
+        
+        self.intFields = intFields
+        self.doubleFields = doubleFields
+    }
+}
+
+extension Date {
+    /// The time when the system was started up.
+    /// Calculated by subtracting the system uptime from the current date.
+    static let systemStartup = Date(timeIntervalSinceNow: -ProcessInfo.processInfo.systemUptime)
+}

Sources/EventTapCore/Model/Event.swift

@@ -0,0 +1,20 @@
+//
+//  EventField.swift
+//  EventTapper
+//
+//  Created by Phil Zakharchenko on 2/23/24.
+//
+
+import Foundation
+
+public protocol EventField: Identifiable, Hashable, Sendable {
+    associatedtype Key: EventInfoKey where Key.RawValue: BinaryInteger
+    associatedtype Value: Numeric & CustomStringConvertible
+    
+    var key: Key { get }
+    var value: Value { get }
+}
+
+extension EventField {
+    public var id: Key.RawValue { key.rawValue }
+}