Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46)

AGENTS.md

@@ -189,7 +189,10 @@ MistKit/
 | `CloudKitService+Initialization.swift` | initializer overloads (API token, web auth token, server-to-server) |
 | `CloudKitService+Operations.swift` | `queryRecords`, `queryAllRecords`, `lookupRecords` |
 | `CloudKitService+WriteOperations.swift` | `modifyRecords`, `createRecord`, `updateRecord`, `deleteRecord` |
-| `CloudKitService+ZoneOperations.swift` | `listZones`, `lookupZones(zoneIDs:)`, `fetchZoneChanges(syncToken:)` |
+| `CloudKitService+ZoneOperations.swift` | `listZones`, `lookupZones(zoneIDs:)`, `fetchZoneChanges(syncToken:)` *(deprecated — see `CloudKitService+DatabaseChanges.swift`)* |
+| `CloudKitService+DatabaseChanges.swift` | `fetchDatabaseChanges(syncToken:resultsLimit:)`, `fetchAllDatabaseChanges(...)` — `changes/database` |
+| `CloudKitService+RecordZoneChanges.swift` | `fetchRecordZoneChanges(zones:...)` — `changes/zone` |
+| `CloudKitService+RecordZoneChangesPagination.swift` | `fetchAllRecordZoneChanges(zones:...)` — per-zone auto-pagination |
 | `CloudKitService+ModifyZones.swift` | `modifyZones(_:database:)` |
 | `CloudKitService+SyncOperations.swift` | `fetchRecordChanges(recordType:syncToken:)`, `fetchAllRecordChanges(recordType:syncToken:)` |
 | `CloudKitService+UserOperations.swift` | `fetchCaller()`, `discoverUserIdentities(lookupInfos:)`, `discoverAllUserIdentities()` *(no-arg address-book form — unavailable, pending #28; distinct from the available `discoverAllUserIdentities(lookupInfos:batchSize:)` chunking overload below)*, `lookupUsersByEmail(_:)`, `lookupUsersByRecordName(_:)` |
@@ -213,7 +216,9 @@ MistKit/
 **Sync/Change Operations:**
 - `fetchRecordChanges(recordType:syncToken:)` → `/records/changes` — returns `RecordChangesResult` with `records`, `syncToken`, `moreComing`
 - `fetchAllRecordChanges(recordType:syncToken:)` — convenience wrapper that auto-paginates using `moreComing`
-- `fetchZoneChanges(syncToken:)` → `/zones/changes` — returns `ZoneChangesResult`
+- `fetchZoneChanges(syncToken:)` → `/zones/changes` — returns `ZoneChangesResult`. **Deprecated** (`@available(*, deprecated)`): Apple deprecated `zones/changes` in favor of `changes/database`. Same for `fetchAllZoneChanges`.
+- `fetchDatabaseChanges(syncToken:resultsLimit:)` → `/changes/database` — returns `DatabaseChangesResult` (*which zones* changed). Replacement for `fetchZoneChanges`. `fetchAllDatabaseChanges(...)` auto-paginates with `maxPages` + stuck-token detection.
+- `fetchRecordZoneChanges(zones:...)` → `/changes/zone` — returns `RecordZoneChangesResult` (records *within* zones). Each zone carries its **own** `syncToken`/`moreComing`, so `fetchAllRecordZoneChanges(...)` re-requests only the zones still reporting `moreComing` and merges each zone's records across rounds (`ZoneChangesAccumulator`).
 - `lookupZones(zoneIDs:)` → `/zones/lookup` — returns `[ZoneInfo]`
 - `discoverUserIdentities(lookupInfos:)` → POST `/users/discover` — takes `[UserIdentityLookupInfo]`, returns `[UserIdentity]`
 
@@ -248,8 +253,14 @@ In MistDemo, integration runs targeting these endpoints use `PhaseContext.userCo
 **Result Types (Sources/MistKit/Models/ and Sources/MistKit/Models/Zones/):**
 - `QueryResult` — `records: [RecordInfo]`, `continuationMarker: String?`
 - `RecordChangesResult` — `records: [RecordInfo]`, `syncToken: String?`, `moreComing: Bool`
-- `ZoneChangesResult` — `zones: [ZoneInfo]`, `syncToken: String?`, `moreComing: Bool`
+- `ZoneChangesResult` — `zones: [ZoneInfo]`, `syncToken: String?`, `moreComing: Bool` *(deprecated `zones/changes`)*
 - `ZoneInfo` — `zoneName: String`, `ownerRecordName: String?`, `capabilities: [String]`, `syncToken: String?`, `atomic: Bool?`
+- `DatabaseChangesResult` — `zones: [ZoneChangeResult]`, `syncToken: String?`, `moreComing: Bool`, plus `changedZones`/`failures` conveniences
+- `RecordZoneChangesResult` — `zones: [ZoneRecordChangesResult]`, plus `changes`/`failures`/`moreComing` conveniences (no top-level sync token — `changes/zone` paginates per zone)
+- `ZoneRecordChanges` — one zone's `records: [RecordInfo]` + that zone's own `syncToken`/`moreComing`
+- `ZoneChangesRequest` — a per-zone entry in a `changes/zone` request (`zoneID` + optional per-zone overrides)
+
+**Per-zone failures (RecordResult pattern):** `changes/database` and `changes/zone` return an entry per zone that is *either* a success payload or a zone fetch error, modeled in `openapi.yaml` as `oneOf: [ZoneFetchFailure, <Success>]`. These surface as `OperationResult<_, ZoneTarget>` (`ZoneChangeResult` / `ZoneRecordChangesResult`) so a failure on one zone never discards the zones that succeeded — matching the `RecordResult` pattern. `ZoneOperationFailure` is keyed by `zoneName` (CloudKit identifies the failed item by `zoneID`, not a flat string), and `.get()` throws `CloudKitError.zoneOperationFailed`.
 - `UserIdentity` — `userRecordName: String?`, `nameComponents: NameComponents?`, `lookupInfo: UserIdentityLookupInfo?`
 - `UserIdentityLookupInfo` — `emailAddress: String?`, `phoneNumber: String?`, `userRecordName: String?`
 - `NameComponents` — full personal name parts (givenName, familyName, nickname, etc.)

Examples/MistDemo/Sources/MistDemoKit/Commands/FetchDatabaseChangesCommand.swift

@@ -0,0 +1,171 @@
+//
+//  FetchDatabaseChangesCommand.swift
+//  MistDemo
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+internal import Foundation
+internal import MistKit
+
+/// Command to fetch which record zones changed with incremental sync.
+///
+/// Wraps `changes/database`, the current replacement for the deprecated
+/// `zones/changes` operation. Reports *which* zones changed; pair with
+/// `fetch-zone-record-changes` to fetch the record changes inside them.
+public struct FetchDatabaseChangesCommand: MistDemoCommand, OutputFormatting {
+  /// The configuration type.
+  public typealias Config = FetchDatabaseChangesConfig
+  /// The command name.
+  public static let commandName = "fetch-database-changes"
+  /// The command abstract.
+  public static let abstract =
+    "Fetch which record zones changed with incremental sync"
+  /// The command help text.
+  public static let helpText = """
+    FETCH-DATABASE-CHANGES - Fetch database (zone-level) changes
+
+    USAGE:
+      mistdemo fetch-database-changes [options]
+
+    OPTIONS:
+      --sync-token <token>     Sync token from previous fetch
+      --fetch-all              Auto-paginate all changes
+      --limit <count>          Max zone changes per page
+      --database <type>        Database to target
+      --output-format <format> Output format
+
+    EXAMPLES:
+      mistdemo fetch-database-changes
+      mistdemo fetch-database-changes --fetch-all
+      mistdemo fetch-database-changes --sync-token "token"
+
+    NOTES:
+      Reports which zones changed; follow up with
+      fetch-zone-record-changes to fetch the records inside them.
+      Save the returned sync token for next fetch.
+    """
+
+  private let config: FetchDatabaseChangesConfig
+
+  /// Creates a new instance.
+  public init(config: FetchDatabaseChangesConfig) {
+    self.config = config
+  }
+
+  /// Executes the command.
+  public func execute() async throws {
+    print("\n" + String(repeating: "=", count: 60))
+    print("🔄 Fetch Database Changes")
+    print(String(repeating: "=", count: 60))
+
+    let service = try MistKitClientFactory.create(
+      for: config.base
+    )
+
+    printSyncTokenStatus()
+
+    if config.fetchAll {
+      try await fetchAllChanges(service: service)
+    } else {
+      try await fetchSinglePage(service: service)
+    }
+
+    print("\n" + String(repeating: "=", count: 60))
+    print("✅ Fetch completed!")
+    print(String(repeating: "=", count: 60))
+  }
+
+  private func printSyncTokenStatus() {
+    if let token = config.syncToken {
+      print("   Using sync token: \(token.prefix(20))...")
+    } else {
+      print("   Performing initial fetch (no sync token)")
+    }
+  }
+
+  private func fetchAllChanges(service: CloudKitService) async throws {
+    print("\n📦 Fetching all database changes (automatic pagination)...")
+    let (zones, newToken) = try await service.fetchAllDatabaseChanges(
+      syncToken: config.syncToken,
+      resultsLimit: config.limit,
+      database: config.base.database
+    )
+    print("\n✅ Fetched \(zones.count) changed zone(s)")
+    displayZones(zones)
+    if let token = newToken {
+      print("\n💾 New sync token: \(token.prefix(20))...")
+      print("   mistdemo fetch-database-changes --sync-token '\(token)'")
+    }
+  }
+
+  private func fetchSinglePage(service: CloudKitService) async throws {
+    print("\n📄 Fetching single page...")
+    let result = try await service.fetchDatabaseChanges(
+      syncToken: config.syncToken,
+      resultsLimit: config.limit,
+      database: config.base.database
+    )
+    print("\n✅ Fetched \(result.zones.count) zone change(s)")
+    displayZones(result.zones)
+
+    if result.moreComing, let token = result.syncToken {
+      print("\n⚠️  More changes available!")
+      print("   mistdemo fetch-database-changes --sync-token '\(token)'")
+    }
+
+    if let token = result.syncToken {
+      print("\n💾 Sync token: \(token.prefix(20))...")
+    }
+    print("   More coming: \(result.moreComing)")
+  }
+
+  private func displayZones(_ zones: [ZoneChangeResult]) {
+    let changed = zones.compactMap { result in
+      if case .success(let zone) = result { return zone }
+      return nil
+    }
+    for zone in changed.prefix(10) {
+      print("   📁 \(zone.zoneName)")
+    }
+    if changed.count > 10 {
+      print("   ... and \(changed.count - 10) more")
+    }
+    displayFailures(
+      zones.compactMap { result in
+        if case .failure(let failure) = result { return failure }
+        return nil
+      }
+    )
+  }
+
+  private func displayFailures(_ failures: [ZoneOperationFailure]) {
+    guard !failures.isEmpty else { return }
+    print("\n⚠️  \(failures.count) zone failure(s):")
+    for failure in failures {
+      print("   - \(failure.zoneName): \(failure.serverErrorCode)")
+    }
+  }
+}

Examples/MistDemo/Sources/MistDemoKit/Commands/FetchZoneRecordChangesCommand.swift

@@ -0,0 +1,158 @@
+//
+//  FetchZoneRecordChangesCommand.swift
+//  MistDemo
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+internal import Foundation
+internal import MistKit
+
+/// Command to fetch record changes within one or more CloudKit zones.
+///
+/// Wraps `changes/zone`. Typically paired with `fetch-database-changes`,
+/// which reports *which* zones changed; this command fetches the record
+/// changes inside them. Each zone paginates independently.
+public struct FetchZoneRecordChangesCommand: MistDemoCommand, OutputFormatting {
+  /// The configuration type.
+  public typealias Config = FetchZoneRecordChangesConfig
+  /// The command name.
+  public static let commandName = "fetch-zone-record-changes"
+  /// The command abstract.
+  public static let abstract =
+    "Fetch record changes within one or more CloudKit zones"
+  /// The command help text.
+  public static let helpText = """
+    FETCH-ZONE-RECORD-CHANGES - Fetch record changes within zones
+
+    USAGE:
+      mistdemo fetch-zone-record-changes [options]
+
+    OPTIONS:
+      --zone-names <names>     Comma-separated zone names (default: _defaultZone)
+      --sync-token <token>     Sync token applied to every requested zone
+      --fetch-all              Auto-paginate all changes (per zone)
+      --limit <count>          Max results per zone per page (1-200)
+      --fields <fields>        Comma-separated fields (desiredKeys)
+      --record-types <types>   Comma-separated record types to include
+      --database <type>        Database to target
+      --output-format <format> Output format
+
+    EXAMPLES:
+      mistdemo fetch-zone-record-changes
+      mistdemo fetch-zone-record-changes --zone-names "Articles,Photos"
+      mistdemo fetch-zone-record-changes --fetch-all
+
+    NOTES:
+      Each zone paginates independently — a sync token and moreComing
+      flag are returned per zone rather than once for the whole request.
+    """
+
+  private let config: FetchZoneRecordChangesConfig
+
+  /// Creates a new instance.
+  public init(config: FetchZoneRecordChangesConfig) {
+    self.config = config
+  }
+
+  /// Executes the command.
+  public func execute() async throws {
+    print("\n" + String(repeating: "=", count: 60))
+    print("🔄 Fetch Zone Record Changes")
+    print(String(repeating: "=", count: 60))
+
+    let service = try MistKitClientFactory.create(
+      for: config.base
+    )
+    let zones = config.zones.map {
+      ZoneChangesRequest(
+        zoneID: ZoneID(zoneName: $0, ownerName: nil),
+        syncToken: config.syncToken,
+        desiredKeys: config.desiredKeys,
+        resultsLimit: config.limit,
+        desiredRecordTypes: config.desiredRecordTypes
+      )
+    }
+
+    print("\n📋 Requesting changes for \(zones.count) zone(s):")
+    for name in config.zones {
+      print("   - \(name)")
+    }
+
+    if config.fetchAll {
+      try await fetchAllChanges(service: service, zones: zones)
+    } else {
+      try await fetchSinglePage(service: service, zones: zones)
+    }
+
+    print("\n" + String(repeating: "=", count: 60))
+    print("✅ Fetch completed!")
+    print(String(repeating: "=", count: 60))
+  }
+
+  private func fetchAllChanges(
+    service: CloudKitService, zones: [ZoneChangesRequest]
+  ) async throws {
+    print("\n📦 Fetching all zone record changes (automatic pagination)...")
+    let result = try await service.fetchAllRecordZoneChanges(
+      zones: zones,
+      database: config.base.database
+    )
+    displayResult(result)
+  }
+
+  private func fetchSinglePage(
+    service: CloudKitService, zones: [ZoneChangesRequest]
+  ) async throws {
+    print("\n📄 Fetching single page for each zone...")
+    let result = try await service.fetchRecordZoneChanges(
+      zones: zones,
+      database: config.base.database
+    )
+    displayResult(result)
+  }
+
+  private func displayResult(_ result: RecordZoneChangesResult) {
+    print("\n✅ Fetched changes for \(result.changes.count) zone(s)")
+    for change in result.changes {
+      print("   📁 \(change.zone.zoneName): \(change.records.count) record(s)")
+      if let token = change.syncToken {
+        print("      Sync token: \(token.prefix(20))...")
+      }
+      if change.moreComing {
+        print("      ⚠️  More changes available for this zone")
+      }
+    }
+
+    if !result.failures.isEmpty {
+      print("\n⚠️  \(result.failures.count) zone failure(s):")
+      for failure in result.failures {
+        print("   - \(failure.zoneName): \(failure.serverErrorCode)")
+      }
+    }
+
+    print("\n   Overall more coming: \(result.moreComing)")
+  }
+}