An API client for ipx, and its event stream (#1)

Everything native needs this first, and it is worth having whatever happens
to the rest: a CarPlay browse tree is built from exactly these calls.

API covers what a client reads and writes -- feeds, entries with the
server's own paging, filtering, sorting and search, read and pinned,
position, read-all, download, delete, fetch -- and APIModels is what ipx
sends, with the server's field names kept so a type here can be checked
against web.rs without translating first. It sends nothing of its own to
authenticate: ipx decides who is asking by cookie and CookieBridge keeps
HTTPCookieStorage in step, which is the same property that lets a plain
<audio src> work.

Events reads /api/events with URLSession's byte stream, so there is no new
dependency. An event this build has never heard of decodes as .other rather
than throwing, because a new one on the server must not stop the stream. It
reconnects with a backoff: a deploy closes the stream cleanly and should be
picked straight back up, a daemon that is down should not be hammered.

Library is gone, folded into API. Two clients writing positions was one too
many, and the page's forwarded beacon no longer carries a path: it asks the
host to save, and the host uses its own clock, which is the only one not
stale when the web view has been frozen in the background.

The tests run against the browser suite's fixture daemon rather than canned
JSON, because the shapes being decoded are the server's and a fixture would
only prove it matches itself. Thirteen pass, including a live scan reported
over SSE and the playback round trip, which still works after the move.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

ios/Tests/APITests.swift

@@ -0,0 +1,120 @@
+import XCTest
+@testable import iPodderX
+
+/// The client against a real daemon, because the shapes it decodes are the server's and a
+/// hand-written fixture would only prove the fixture matches itself.
+///
+/// Point it at the daemon the browser suite uses, in ipodderx-rs:
+///
+///   node -e "require('./tests/ui/global-setup').prepare()"
+///   node tests/ui/fixtures/serve.js &
+///   IPX_CONFIG=$ROOT/config/config.toml IPX_DATA_DIR=$ROOT/data ./target/debug/ipx daemon &
+///   TEST_RUNNER_IPX_SERVER=http://127.0.0.1:8791 TEST_RUNNER_IPX_TOKEN=<fixture token> \
+///     xcodebuild test ...
+final class APITests: XCTestCase {
+    var api: API!
+
+    override func setUpWithError() throws {
+        let env = ProcessInfo.processInfo.environment
+        let server = env["IPX_SERVER"] ?? ""
+        let token = env["IPX_TOKEN"] ?? ""
+        try XCTSkipIf(server.isEmpty, "set IPX_SERVER to a fixture daemon")
+
+        ServerSettings.base = try XCTUnwrap(ServerSettings.parse(server))
+
+        // The shared token signs in as the admin. It goes in as a cookie rather than on the
+        // query because that is how the client authenticates everything -- ipx reads
+        // HTTPCookieStorage through the same path the web view fills.
+        if !token.isEmpty, let url = ServerSettings.base {
+            let cookie = try XCTUnwrap(HTTPCookie(properties: [
+                .name: "ipx_token", .value: token, .path: "/",
+                .domain: url.host ?? "127.0.0.1",
+            ]))
+            HTTPCookieStorage.shared.setCookie(cookie)
+        }
+        api = API()
+    }
+
+    func testSignedIn() async throws {
+        let me = try await api.me()
+        XCTAssertFalse(me.name.isEmpty, "nobody is signed in")
+    }
+
+    func testFeedsDecode() async throws {
+        let feeds = try await api.feeds()
+        XCTAssertFalse(feeds.isEmpty, "the fixture daemon has five feeds configured")
+        let show = try XCTUnwrap(feeds.first { $0.id == "test-show" }, "no test-show feed")
+        XCTAssertEqual(show.name, "Test Show")
+        XCTAssertEqual(show.entries, 2)
+        XCTAssertGreaterThanOrEqual(show.subscribers, 1)
+    }
+
+    func testEntriesPageAndDecodeEnclosures() async throws {
+        let page = try await api.entries(feed: "test-show")
+        XCTAssertEqual(page.total, 2)
+        let second = try XCTUnwrap(page.entries.first { $0.guid == "ui-2" })
+        XCTAssertEqual(second.feedId, "test-show")
+        // The cap is one download per scan, newest first, so the second episode has the file.
+        let file = try XCTUnwrap(second.playable, "the downloaded episode has no playable file")
+        XCTAssertTrue(file.isDownloaded)
+        XCTAssertEqual(file.mime, "audio/mpeg")
+        XCTAssertFalse(file.isVideo)
+    }
+
+    /// An image enclosure is on disk and is not a thing to hand a player.
+    func testAnImageIsNotPlayable() async throws {
+        let page = try await api.entries(feed: "picture-blog")
+        let enclosure = try XCTUnwrap(page.entries.first?.enclosures.first)
+        XCTAssertTrue(enclosure.isDownloaded)
+        XCTAssertFalse(enclosure.isPlayable, "a downloaded JPEG is not something to play")
+    }
+
+    func testFilterAndSortAreTheServersWork() async throws {
+        let downloaded = try await api.entries(feed: "test-show", filter: .downloaded)
+        XCTAssertEqual(downloaded.total, 1, "one of the two episodes has a file")
+
+        let asc = try await api.entries(feed: "test-show", sort: .title, direction: .asc)
+        let desc = try await api.entries(feed: "test-show", sort: .title, direction: .desc)
+        XCTAssertEqual(asc.entries.map(\.guid), desc.entries.map(\.guid).reversed())
+    }
+
+    func testSearchMatchesTitles() async throws {
+        let hit = try await api.entries(feed: "test-show", search: "Second")
+        XCTAssertEqual(hit.entries.count, 1)
+        let miss = try await api.entries(feed: "test-show", search: "nothing matches this")
+        XCTAssertEqual(miss.total, 0)
+    }
+
+    /// Read is per-person state, so writing it and reading it back is the whole contract.
+    func testReadRoundTrips() async throws {
+        let before = try await api.entries(feed: "test-show", filter: .all)
+        let entry = try XCTUnwrap(before.entries.first { $0.guid == "ui-1" })
+
+        try await api.setRead(!entry.read, feed: entry.feedId, guid: entry.guid)
+        let after = try await api.entries(feed: "test-show")
+        let again = try XCTUnwrap(after.entries.first { $0.guid == "ui-1" })
+        XCTAssertEqual(again.read, !entry.read, "the flag did not stick")
+
+        try await api.setRead(entry.read, feed: entry.feedId, guid: entry.guid)
+    }
+
+    func testPositionRoundTrips() async throws {
+        try await api.setPosition(secs: 42, duration: 900, feed: "test-show", guid: "ui-2")
+        let page = try await api.entries(feed: "test-show")
+        XCTAssertEqual(page.entries.first { $0.guid == "ui-2" }?.position, 42)
+        try await api.setPosition(secs: 0, duration: nil, feed: "test-show", guid: "ui-2")
+    }
+
+    /// A 401 has to be legible: it means the session went, and only a sign-in fixes it.
+    func testAnUnauthenticatedCallSaysSoPlainly() async throws {
+        HTTPCookieStorage.shared.removeCookies(since: .distantPast)
+        do {
+            _ = try await api.feeds()
+            XCTFail("a signed-out request should not succeed")
+        } catch API.Failure.notSignedIn {
+            // what we want
+        } catch {
+            XCTFail("expected notSignedIn, got \(error)")
+        }
+    }
+}