Add CalendarrCore: the shared read contract for the calendar snapshot

Calendarr already publishes an event snapshot into its App Group container for the widgets to render. That channel is what a second Mac app needs too, so this turns an internal detail into a documented contract rather than something a second app reverse-engineers and then drifts from. Foundation only — no SwiftUI, no UIKit, no AppKit — so one source compiles for iOS, Mac Catalyst and native macOS. Building against the native macOS SDK is the point: it fails loudly on a UIKit leak that a Catalyst build would accept. Three things earn their place here rather than being copied per app: CalendarrAppGroup resolves the container identifier per platform. macOS requires the Team ID prefix and iOS forbids it, and a mismatch fails silently — nil container, every read and write a no-op, widgets blank forever. CalendarKey normalises the two ways the server reports calendar_id (bare for CalDAV, "local-3" style for everything else). Normalising them differently is what made per-calendar filtering quietly do nothing for some sources. The snapshot schema is versioned, with the coverage window now explicit. That window is the easiest thing to get wrong downstream: outside it the snapshot carries no information, which is not the same as no events, and rendering an empty week for an uncovered date produces a screen that looks right and is false. covers() exists so consumers can tell the two apart. Reads return a named result rather than an optional. "Never ran", "signed out", "too new to read" and "unreadable" need different messages, and a bare nil is how the App Group misconfiguration used to hide. Writing is behind @_spi(Writer) so a read-only consumer cannot corrupt the shared cache. Writes post a Darwin notification, the one cross-process signal that works between two sandboxed apps without an extra entitlement. The six colour values stay flat on the wire instead of nesting under `theme`, which would read better. A v1 reader requires them flat, so nesting would have broken every older build on the first v2 write; `theme` is a computed view. Tests pin both directions of compatibility, since the two apps ship independently. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 17:30:23 +02:00
commit ab2328969e
11 changed files with 920 additions and 0 deletions
@@ -0,0 +1,85 @@
+import Foundation
+
+/// Non-secret session facts published alongside the snapshot.
+///
+/// This exists so a consumer can answer "which server, and is anyone signed in?"
+/// without reading Calendarr's own `UserDefaults`, which lives in a different
+/// sandbox. The auth token is deliberately *not* here — it belongs in the shared
+/// keychain group, not in a plain file in the container.
+public struct SharedSession: Codable, Sendable {
+    public static let currentSchema = 1
+    public static let maxSupportedSchema = 1
+
+    public let schemaVersion: Int
+    public let baseURL: String
+    public let username: String
+    public let isLoggedIn: Bool
+    public let writtenAt: Date
+
+    public init(baseURL: String, username: String, isLoggedIn: Bool, writtenAt: Date) {
+        self.schemaVersion = Self.currentSchema
+        self.baseURL = baseURL
+        self.username = username
+        self.isLoggedIn = isLoggedIn
+        self.writtenAt = writtenAt
+    }
+
+    public init(from decoder: Decoder) throws {
+        let c = try decoder.container(keyedBy: CodingKeys.self)
+        schemaVersion = try c.decodeIfPresent(Int.self, forKey: .schemaVersion) ?? 1
+        baseURL       = try c.decode(String.self, forKey: .baseURL)
+        username      = try c.decodeIfPresent(String.self, forKey: .username) ?? ""
+        isLoggedIn    = try c.decodeIfPresent(Bool.self, forKey: .isLoggedIn) ?? true
+        writtenAt     = try c.decodeIfPresent(Date.self, forKey: .writtenAt) ?? Date(timeIntervalSince1970: 0)
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case schemaVersion, baseURL, username, isLoggedIn, writtenAt
+    }
+
+    /// The server URL as a `URL`, or nil when unset or malformed.
+    public var url: URL? { baseURL.isEmpty ? nil : URL(string: baseURL) }
+}
+
+public struct SharedSessionStore: Sendable {
+    private static let filename = "session.json"
+
+    public let appGroupID: String
+
+    public init(appGroupID: String = CalendarrAppGroup.current) {
+        self.appGroupID = appGroupID
+    }
+
+    private var fileURL: URL? {
+        FileManager.default
+            .containerURL(forSecurityApplicationGroupIdentifier: appGroupID)?
+            .appendingPathComponent(Self.filename)
+    }
+
+    /// Nil when Calendarr has never published, or the file is unreadable or newer
+    /// than this reader understands.
+    public func read() -> SharedSession? {
+        guard let url = fileURL, let data = try? Data(contentsOf: url) else { return nil }
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .iso8601
+        guard let session = try? decoder.decode(SharedSession.self, from: data),
+              session.schemaVersion <= SharedSession.maxSupportedSchema else { return nil }
+        return session
+    }
+
+    @_spi(Writer)
+    public func write(_ session: SharedSession) throws {
+        guard let url = fileURL else {
+            throw SnapshotStoreError.containerUnavailable(appGroupID: appGroupID)
+        }
+        let encoder = JSONEncoder()
+        encoder.dateEncodingStrategy = .iso8601
+        try encoder.encode(session).write(to: url, options: .atomic)
+    }
+
+    @_spi(Writer)
+    public func clear() {
+        guard let url = fileURL else { return }
+        try? FileManager.default.removeItem(at: url)
+    }
+}