@candypoets/nipworker 0.96.3 → 0.96.5

package/swift/README.md

@@ -0,0 +1,438 @@
+# NipworkerSwift
+
+Swift bindings for NIPWorker — a high-performance Nostr client library powered by Rust WebAssembly and FlatBuffers. This package wraps the Rust native FFI layer to provide an async-first, actor-safe Swift API for subscribing to relays, publishing events, and managing cryptographic signers.
+
+## Requirements
+
+- **iOS 14+** / **macOS 13+**
+- **Swift 5.9+**
+- **Xcode 15+** (recommended)
+
+## Installation
+
+### Xcode — Local Package (recommended while iterating)
+
+1. Open your iOS/macOS project in Xcode.
+2. Go to **File → Add Package Dependencies…**
+3. Click **Add Local…** and select the `swift/` folder inside this repository.
+4. Add `NipworkerSwift` to your app target.
+
+> **Note on the XCFramework path**: `Package.swift` references the XCFramework via a relative path (`../crates/native-ffi/ios/`). Some Xcode/SPM versions reject binary targets that live outside the package root. If you hit this, copy or symlink the framework into the package:
+>
+> ```bash
+> mkdir -p swift/Frameworks
+> cp -R crates/native-ffi/ios/NipworkerNativeFFI.xcframework swift/Frameworks/
+> ```
+>
+> Then change the `binaryTarget` path in `swift/Package.swift` to `"Frameworks/NipworkerNativeFFI.xcframework"`.
+
+### Swift Package Manager
+
+Add the following to your `Package.swift`:
+
+```swift
+// swift-tools-version:5.9
+import PackageDescription
+
+let package = Package(
+    name: "YourApp",
+    platforms: [.iOS(.v14), .macOS(.v13)],
+    dependencies: [
+        .package(name: "NipworkerSwift", path: "../path-to-nipworker-repo/swift")
+    ],
+    targets: [
+        .executableTarget(
+            name: "YourApp",
+            dependencies: ["NipworkerSwift"]
+        )
+    ]
+)
+```
+
+## Quick Start
+
+```swift
+import NipworkerSwift
+
+let manager = NostrManager()
+
+let request = RequestObject(
+    filters: [.init(kinds: [1], limit: 10)],
+    relays: ["wss://relay.damus.io"]
+)
+
+let buffer = await manager.subscribe(
+    subscriptionId: "feed",
+    requests: [request]
+)
+
+let unsub = useSubscription(
+    manager: manager,
+    subscriptionId: "feed",
+    requests: [request]
+) { events in
+    for event in events {
+        print("Event:", event.id, event.content)
+    }
+}
+```
+
+## API Reference
+
+### `NostrManager`
+
+The core actor that owns the Rust engine handle. All methods are `async` or return values synchronously from the actor's isolated state.
+
+```swift
+public actor NostrManager {
+    public init(config: NostrManagerConfig = NostrManagerConfig())
+
+    // Subscription
+    public func subscribe(
+        subscriptionId: String,
+        requests: [RequestObject],
+        options: SubscriptionConfig = SubscriptionConfig()
+    ) -> SubscriptionBuffer
+
+    public func unsubscribe(subscriptionId: String)
+
+    // Publish
+    public func publish(
+        publishId: String,
+        event: NostrEvent,
+        defaultRelays: [String] = [],
+        optimisticSubIds: [String] = []
+    ) -> SubscriptionBuffer
+
+    // Signer
+    public func setSigner(_ signer: SignerTypeName)
+    public func getPublicKey() async throws -> String
+    public func signEvent(_ template: EventTemplate) async throws -> NostrEvent
+    public func logout()
+
+    // Read helpers
+    public func readEvents(for subId: String, from position: Int) -> (events: [NostrEvent], newPosition: Int)
+    public func readPublishStatuses(for publishId: String, from position: Int) -> (statuses: [String: PublishStatus], newPosition: Int)
+    public func getRelayStatuses() -> [String: RelayStatus]
+    public func getActivePubkey() -> String?
+
+    public func cleanup()
+}
+```
+
+### Models
+
+#### `RequestObject`
+
+Defines a Nostr filter + relay set.
+
+```swift
+public struct RequestObject {
+    public var ids: [String]?
+    public var authors: [String]?
+    public var kinds: [UInt16]?
+    public var tags: [String: [String]]?
+    public var since: Int?
+    public var until: Int?
+    public var limit: Int?
+    public var search: String?
+    public var relays: [String]
+    public var closeOnEOSE: Bool?
+    public var cacheFirst: Bool?
+    public var noCache: Bool?
+    public var maxRelays: UInt16?
+}
+```
+
+#### `SubscriptionConfig`
+
+Controls subscription behavior.
+
+```swift
+public struct SubscriptionConfig {
+    public var pipeline: [PipeConfig]?
+    public var closeOnEose: Bool
+    public var cacheFirst: Bool
+    public var timeoutMs: UInt64?
+    public var maxEvents: UInt32?
+    public var skipCache: Bool
+    public var force: Bool
+    public var bytesPerEvent: UInt32
+    public var isSlow: Bool
+    public var pagination: String?
+    public var cacheOnly: Bool
+}
+```
+
+#### `NostrEvent`
+
+```swift
+public struct NostrEvent: Identifiable, Equatable, Sendable {
+    public var id: String
+    public var pubkey: String
+    public var kind: UInt16
+    public var content: String
+    public var tags: [[String]]
+    public var createdAt: Int
+    public var sig: String
+}
+```
+
+#### `EventTemplate`
+
+Used when signing a new event.
+
+```swift
+public struct EventTemplate {
+    public var kind: UInt16
+    public var content: String
+    public var tags: [[String]]
+}
+```
+
+#### `SignerTypeName`
+
+```swift
+public enum SignerTypeName: Sendable {
+    case pubkey(String)
+    case privkey(String)
+}
+```
+
+#### `RelayStatus`
+
+```swift
+public enum RelayStatus: Equatable, Sendable {
+    case connected
+    case failed
+    case closed(String?)
+}
+```
+
+#### `PublishStatus`
+
+```swift
+public enum PublishStatus: Equatable, Sendable {
+    case pending
+    case success(String)
+    case failed(String)
+}
+```
+
+### Hooks
+
+Callback-based helpers that mirror the JS `useSubscription` / `usePublish` / `useRelayStatus` hooks. They return an unsubscribe function.
+
+```swift
+public func useSubscription(
+    manager: NostrManager,
+    subscriptionId: String,
+    requests: [RequestObject],
+    callback: @escaping ([NostrEvent]) -> Void,
+    options: SubscriptionConfig = SubscriptionConfig()
+) -> () -> Void
+
+public func usePublish(
+    manager: NostrManager,
+    publishId: String,
+    event: NostrEvent,
+    callback: @escaping ([String: PublishStatus]) -> Void,
+    defaultRelays: [String] = [],
+    optimisticSubIds: [String] = []
+) -> () -> Void
+
+public func useRelayStatus(
+    manager: NostrManager,
+    onStatus: @escaping (String, RelayStatus) -> Void
+) -> () -> Void
+```
+
+### SwiftUI Helpers
+
+#### `Subscription`
+
+An `@MainActor ObservableObject` that wraps a subscription and exposes `@Published` events.
+
+```swift
+@MainActor
+public final class Subscription: ObservableObject {
+    @Published public private(set) var events: [NostrEvent] = []
+    @Published public private(set) var isComplete: Bool = false
+    public let id: String
+
+    public init(id: String, manager: NostrManager)
+}
+```
+
+#### `PublishTracker`
+
+An `@MainActor ObservableObject` that tracks publish statuses.
+
+```swift
+@MainActor
+public final class PublishTracker: ObservableObject {
+    @Published public private(set) var statuses: [String: PublishStatus] = [:]
+    public let publishId: String
+
+    public init(publishId: String, manager: NostrManager)
+}
+```
+
+## Examples
+
+### Subscribe & display events in SwiftUI
+
+```swift
+import SwiftUI
+import NipworkerSwift
+
+@MainActor
+class FeedViewModel: ObservableObject {
+    let manager = NostrManager()
+    let sub: Subscription
+
+    init() {
+        sub = Subscription(id: "feed", manager: manager)
+    }
+
+    func start() async {
+        let request = RequestObject(
+            filters: [.init(kinds: [1], limit: 50)],
+            relays: ["wss://relay.damus.io"]
+        )
+        _ = await manager.subscribe(
+            subscriptionId: "feed",
+            requests: [request]
+        )
+    }
+}
+
+struct FeedView: View {
+    @StateObject var vm = FeedViewModel()
+
+    var body: some View {
+        List(vm.sub.events) { event in
+            VStack(alignment: .leading) {
+                Text(event.content)
+                    .lineLimit(3)
+                Text("Kind \(event.kind)")
+                    .font(.caption)
+                    .foregroundColor(.secondary)
+            }
+        }
+        .task {
+            await vm.start()
+        }
+    }
+}
+```
+
+### Native login and signer restore
+
+`NostrManager` keeps the active signer in memory only. It does not persist private
+keys, NIP-46 session data, or login state. Native apps should own that policy with
+their own secure storage, typically Keychain on iOS/macOS.
+
+On first login, validate the key by installing it as the signer and asking the
+native engine for the public key:
+
+```swift
+let secret = "your-hex-private-key"
+manager.setSigner(.privkey(secret))
+let pubkey = try await manager.getPublicKey()
+
+let session = AuthSession(
+    pubkey: pubkey,
+    signer: .privateKey(secret)
+)
+
+// App-owned persistence. Store this in Keychain, not UserDefaults.
+let data = try JSONEncoder().encode(session)
+try await keychain.save(data, account: "nostr-auth")
+```
+
+On app restart, load the saved session and restore the native signer explicitly:
+
+```swift
+if let data = try await keychain.load(account: "nostr-auth") {
+    let session = try JSONDecoder().decode(AuthSession.self, from: data)
+
+    switch session.signer {
+    case .privateKey(let secret):
+        manager.setSigner(.privkey(secret))
+        _ = try await manager.getPublicKey()
+    }
+}
+```
+
+The library exposes `AuthSession` as a small `Codable` value so app code can use
+one stable storage format. The actual storage backend is intentionally outside
+`NostrManager`; the host app decides whether to persist, when to restore, whether
+to use biometric gates, and how logout deletes credentials.
+
+`logout()` clears Swift-side auth state for the manager. If the app persisted an
+`AuthSession`, it must also delete that saved session from its own secure store.
+
+### Publish a signed event
+
+```swift
+manager.setSigner(.privkey("your-hex-private-key"))
+_ = try await manager.getPublicKey()
+
+let template = EventTemplate(
+    kind: 1,
+    content: "Hello from Swift!",
+    tags: []
+)
+let event = try await manager.signEvent(template)
+
+let tracker = PublishTracker(publishId: "pub-1", manager: manager)
+
+_ = await manager.publish(
+    publishId: "pub-1",
+    event: event,
+    defaultRelays: ["wss://relay.damus.io"]
+)
+
+// tracker.statuses will update automatically via @Published
+```
+
+### Monitor relay status
+
+```swift
+let unsub = useRelayStatus(manager: manager) { relay, status in
+    print("Relay \(relay): \(status)")
+}
+```
+
+## Architecture
+
+- **Rust FFI** — A static library (`libnipworker_native_ffi.a`) compiled from the `native-ffi` crate and bundled as an `XCFramework`.
+- **FlatBuffers** — All messages crossing the Swift/Rust boundary are serialized with FlatBuffers for zero-allocation parsing on the Rust side.
+- **Actor Isolation** — `NostrManager` is a Swift `actor` so all state mutation is serialized and safe to call from any concurrency context.
+- **Subscription Buffers** — Events arrive from Rust into a shared `SubscriptionBuffer` (a raw pointer with a 4-byte header). Swift reads length-prefixed messages out of the buffer.
+
+## Testing
+
+Run the test suite from the `swift/` directory:
+
+```bash
+cd swift
+swift test
+```
+
+The suite includes:
+- **Unit tests** — `ArrayBufferReaderTests`, `NostrManagerTests`
+- **Integration tests** — Live WebSocket subscription against `wss://relay.damus.io`
+
+> Integration tests require an internet connection and may take a few seconds.
+
+## Known Limitations
+
+- **Swift 6 language mode warnings** — The package compiles and runs correctly, but produces a handful of concurrency warnings (e.g., accessing `handle`/`boxPtr` in the actor initializer). These are non-blocking.
+- **FlatBuffers Object API** — Unavailable due to a `flatc` code-generation bug (`ParsedDataUnion` enum/struct name collision). All serialization uses the low-level builder API.
+- **Native deployment target warnings** — Rebuild `NipworkerNativeFFI.xcframework` with `crates/native-ffi/ios/build-ios.sh`. The script passes explicit iOS and macOS minimum-version linker flags to Rust so the compiled static libraries match the Swift package deployment targets.
+
+## License
+
+Same as the parent NIPWorker project.

package/swift/Sources/NipworkerSwift/ArrayBufferReader.swift

@@ -0,0 +1,136 @@
+import Foundation
+
+/// Wraps a raw mutable buffer allocated with UnsafeMutablePointer.
+/// Buffer format:
+///   [0-3]:  write position (UInt32 little-endian)
+///   [4..]:  [4-byte len][FlatBuffer payload]...
+public final class SubscriptionBuffer {
+    public let pointer: UnsafeMutableRawPointer
+    public let capacity: Int
+    private let ownsMemory: Bool
+
+    public init(capacity: Int) {
+        self.pointer = .allocate(byteCount: capacity, alignment: MemoryLayout<UInt32>.alignment)
+        self.capacity = capacity
+        self.ownsMemory = true
+        // Initialize write position to 4 (right after header)
+        pointer.storeBytes(of: UInt32(4).littleEndian, toByteOffset: 0, as: UInt32.self)
+    }
+
+    public init(pointer: UnsafeMutableRawPointer, capacity: Int) {
+        self.pointer = pointer
+        self.capacity = capacity
+        self.ownsMemory = false
+    }
+
+    deinit {
+        if ownsMemory {
+            pointer.deallocate()
+        }
+    }
+}
+
+public enum ArrayBufferReader {
+    public static func initializeBuffer(_ buffer: SubscriptionBuffer) {
+        buffer.pointer.storeBytes(of: UInt32(4).littleEndian, toByteOffset: 0, as: UInt32.self)
+    }
+
+    public static func writeMessage(buffer: SubscriptionBuffer, data: Data) -> Bool {
+        let currentWritePosition = readWritePosition(buffer)
+        let requiredSpace = 4 + data.count
+        guard currentWritePosition + requiredSpace <= buffer.capacity else {
+            return false
+        }
+
+        buffer.pointer.storeBytes(
+            of: UInt32(data.count).littleEndian,
+            toByteOffset: currentWritePosition,
+            as: UInt32.self
+        )
+        data.copyBytes(to: buffer.pointer.advanced(by: currentWritePosition + 4).assumingMemoryBound(to: UInt8.self), count: data.count)
+
+        let newPosition = currentWritePosition + requiredSpace
+        buffer.pointer.storeBytes(of: UInt32(newPosition).littleEndian, toByteOffset: 0, as: UInt32.self)
+        return true
+    }
+
+    public static func writeBatchedData(buffer: SubscriptionBuffer, data: Data, debugId: String? = nil) -> Bool {
+        let currentWritePosition = readWritePosition(buffer)
+        guard currentWritePosition + data.count <= buffer.capacity else {
+            return false
+        }
+
+        data.copyBytes(to: buffer.pointer.advanced(by: currentWritePosition).assumingMemoryBound(to: UInt8.self), count: data.count)
+
+        let newPosition = currentWritePosition + data.count
+        buffer.pointer.storeBytes(of: UInt32(newPosition).littleEndian, toByteOffset: 0, as: UInt32.self)
+        return true
+    }
+
+    public static func readMessages(
+        buffer: SubscriptionBuffer,
+        lastReadPosition: Int = 0
+    ) -> (messages: [Data], newReadPosition: Int, hasNewData: Bool) {
+        let currentWritePosition = readWritePosition(buffer)
+        let dataStartOffset = 4
+        var currentPos = max(lastReadPosition, dataStartOffset)
+
+        guard currentWritePosition > currentPos else {
+            return ([], currentPos, false)
+        }
+
+        var messages: [Data] = []
+        let maxMessages = 128
+
+        while currentPos < currentWritePosition && messages.count < maxMessages {
+            guard currentPos + 4 <= currentWritePosition else { break }
+
+            let eventLength = Int(
+                UInt32(buffer.pointer.load(fromByteOffset: currentPos, as: UInt8.self)) |
+                (UInt32(buffer.pointer.load(fromByteOffset: currentPos + 1, as: UInt8.self)) << 8) |
+                (UInt32(buffer.pointer.load(fromByteOffset: currentPos + 2, as: UInt8.self)) << 16) |
+                (UInt32(buffer.pointer.load(fromByteOffset: currentPos + 3, as: UInt8.self)) << 24)
+            )
+            let payloadStart = currentPos + 4
+            let nextPos = payloadStart + eventLength
+
+            guard nextPos <= currentWritePosition else { break }
+
+            let slice = Data(bytes: buffer.pointer.advanced(by: payloadStart), count: eventLength)
+            messages.append(slice)
+            currentPos = nextPos
+        }
+
+        return (messages, currentPos, messages.count > 0)
+    }
+
+    public static func readAllMessages(buffer: SubscriptionBuffer) -> (messages: [Data], totalMessages: Int) {
+        let result = readMessages(buffer: buffer, lastReadPosition: 0)
+        return (result.messages, result.messages.count)
+    }
+
+    public static func getCurrentWritePosition(buffer: SubscriptionBuffer) -> Int {
+        return readWritePosition(buffer)
+    }
+
+    public static func hasNewData(buffer: SubscriptionBuffer, lastReadPosition: Int) -> Bool {
+        let currentWritePosition = readWritePosition(buffer)
+        return currentWritePosition > max(lastReadPosition, 4)
+    }
+
+    public static func calculateBufferSize(totalEventLimit: Int = 100, bytesPerEvent: Int = 3072) -> Int {
+        let headerSize = 4
+        let dataSize = totalEventLimit * bytesPerEvent
+        let overhead = Int(Double(dataSize) * 0.25)
+        return headerSize + dataSize + overhead
+    }
+
+    private static func readWritePosition(_ buffer: SubscriptionBuffer) -> Int {
+        return Int(
+            UInt32(buffer.pointer.load(fromByteOffset: 0, as: UInt8.self)) |
+            (UInt32(buffer.pointer.load(fromByteOffset: 1, as: UInt8.self)) << 8) |
+            (UInt32(buffer.pointer.load(fromByteOffset: 2, as: UInt8.self)) << 16) |
+            (UInt32(buffer.pointer.load(fromByteOffset: 3, as: UInt8.self)) << 24)
+        )
+    }
+}

package/swift/Sources/NipworkerSwift/AuthSession.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+public enum AuthSigner: Codable, Equatable, Sendable {
+    case privateKey(String)
+}
+
+public struct AuthSession: Codable, Equatable, Sendable {
+    public var pubkey: String
+    public var signer: AuthSigner
+    public var createdAt: Date
+    public var lastUsedAt: Date?
+
+    public init(
+        pubkey: String,
+        signer: AuthSigner,
+        createdAt: Date = Date(),
+        lastUsedAt: Date? = nil
+    ) {
+        self.pubkey = pubkey
+        self.signer = signer
+        self.createdAt = createdAt
+        self.lastUsedAt = lastUsedAt
+    }
+}

package/swift/Sources/NipworkerSwift/FFI.swift

@@ -0,0 +1,94 @@
+import Darwin
+import Foundation
+
+// MARK: - C FFI Imports from libnipworker_native_ffi
+
+@_silgen_name("nipworker_init")
+func nipworker_init(
+    _ callback: @convention(c) (UnsafeMutableRawPointer?, UnsafePointer<UInt8>?, Int) -> Void,
+    _ userdata: UnsafeMutableRawPointer?
+) -> UnsafeMutableRawPointer?
+
+@_silgen_name("nipworker_handle_message")
+func nipworker_handle_message(
+    _ handle: UnsafeMutableRawPointer?,
+    _ ptr: UnsafePointer<UInt8>?,
+    _ len: Int
+)
+
+@_silgen_name("nipworker_subscribe_message")
+func nipworker_subscribe_message(
+    _ handle: UnsafeMutableRawPointer?,
+    _ ptr: UnsafePointer<UInt8>?,
+    _ len: Int
+) -> Bool
+
+@_silgen_name("nipworker_publish_message")
+func nipworker_publish_message(
+    _ handle: UnsafeMutableRawPointer?,
+    _ ptr: UnsafePointer<UInt8>?,
+    _ len: Int
+) -> Bool
+
+@_silgen_name("nipworker_set_private_key")
+func nipworker_set_private_key(
+    _ handle: UnsafeMutableRawPointer?,
+    _ ptr: UnsafePointer<Int8>?
+)
+
+@_silgen_name("nipworker_deinit")
+func nipworker_deinit(_ handle: UnsafeMutableRawPointer?)
+
+@_silgen_name("nipworker_free_bytes")
+func nipworker_free_bytes(_ ptr: UnsafeMutablePointer<UInt8>?, _ len: Int)
+
+@_silgen_name("nipworker_register_subscription")
+func nipworker_register_subscription(
+    _ handle: UnsafeMutableRawPointer?,
+    _ subId: UnsafePointer<Int8>?,
+    _ bufferSize: Int
+) -> Bool
+
+@_silgen_name("nipworker_register_publish_buffer")
+func nipworker_register_publish_buffer(
+    _ handle: UnsafeMutableRawPointer?,
+    _ publishId: UnsafePointer<Int8>?,
+    _ bufferSize: Int
+) -> Bool
+
+@_silgen_name("nipworker_retain_subscription")
+func nipworker_retain_subscription(
+    _ handle: UnsafeMutableRawPointer?,
+    _ subId: UnsafePointer<Int8>?
+) -> Bool
+
+@_silgen_name("nipworker_release_subscription")
+func nipworker_release_subscription(
+    _ handle: UnsafeMutableRawPointer?,
+    _ subId: UnsafePointer<Int8>?
+)
+
+@_silgen_name("nipworker_subscription_buffer_ptr")
+func nipworker_subscription_buffer_ptr(
+    _ handle: UnsafeMutableRawPointer?,
+    _ subId: UnsafePointer<Int8>?
+) -> UnsafeMutablePointer<UInt8>?
+
+@_silgen_name("nipworker_subscription_buffer_len")
+func nipworker_subscription_buffer_len(
+    _ handle: UnsafeMutableRawPointer?,
+    _ subId: UnsafePointer<Int8>?
+) -> Int
+
+@_silgen_name("nipworker_cleanup_subscriptions")
+func nipworker_cleanup_subscriptions(_ handle: UnsafeMutableRawPointer?)
+
+func nipworker_react_native_shared_handle_if_available() -> UnsafeMutableRawPointer? {
+    typealias SharedHandleFunction = @convention(c) () -> UnsafeMutableRawPointer?
+
+    guard let symbol = dlsym(UnsafeMutableRawPointer(bitPattern: -2), "nipworker_react_native_shared_handle") else {
+        return nil
+    }
+
+    return unsafeBitCast(symbol, to: SharedHandleFunction.self)()
+}