evOo-local/apps/desktop/native/photos-helper/Sources/photos-helper/Library.swift

import Foundation
import Photos
import PhotosHelperCore

/// Read-only PhotoKit queries. Nothing here writes to the library.
struct Library {
  private let library = PHPhotoLibrary.shared()

  /// Images and videos only; audio and unknown media types are not part of Media Studio.
  /// PhotoKit sorts by date only; the store places missing dates first, which is what
  /// `SortKey` assumes, and `nextPage` orders ties itself.
  private func fetchOptions(since: Date?) -> PHFetchOptions {
    let options = PHFetchOptions()
    options.includeHiddenAssets = false
    var predicates = [
      NSPredicate(
        format: "mediaType == %ld || mediaType == %ld",
        PHAssetMediaType.image.rawValue, PHAssetMediaType.video.rawValue)
    ]
    if let since {
      predicates.append(NSPredicate(format: "modificationDate >= %@", since as NSDate))
    }
    options.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: predicates)
    options.sortDescriptors = [NSSortDescriptor(key: "creationDate", ascending: true)]
    return options
  }

  func list(after cursor: ListCursor?, limit: Int, since: Date?) throws -> ListOutput {
    // Captured before enumeration so changes made while listing show up next time.
    let changeToken = try encodeToken(library.currentChangeToken)
    let result = PHAsset.fetchAssets(with: fetchOptions(since: since))
    let page = nextPage(
      count: result.count,
      key: { index in
        let asset = result.object(at: index)
        return SortKey(creationDate: asset.creationDate, localIdentifier: asset.localIdentifier)
      },
      after: cursor,
      limit: limit)
    let assets = page.indices.map { result.object(at: $0) }
    let items = assets.compactMap(makeItem(for:))
    let nextCursor = page.hasMore
      ? assets.last.map {
        ListCursor(key: SortKey(creationDate: $0.creationDate, localIdentifier: $0.localIdentifier))
          .encoded()
      }
      : nil
    return ListOutput(items: items, nextCursor: nextCursor, changeToken: changeToken)
  }

  func asset(_ localIdentifier: String) throws -> AssetOutput {
    guard let asset = PHAsset.fetchAssets(withLocalIdentifiers: [localIdentifier], options: nil).firstObject,
      let item = makeItem(for: asset)
    else { throw HelperError(.notFound, "No photo or video with that identifier.") }
    let resources = PHAssetResource.assetResources(for: asset).map {
      AssetResourceInfo(
        type: resourceTypeName($0.type), fileName: $0.originalFilename, uti: $0.uniformTypeIdentifier)
    }
    return AssetOutput(
      item: item, modifiedAt: asset.modificationDate, hidden: asset.isHidden, resources: resources)
  }

  /// Persistent change history (macOS 13). An expired token or missing history asks the
  /// caller for a full relisting instead of guessing.
  func changes(since encodedToken: String) throws -> ChangesOutput {
    guard let token = decodeToken(encodedToken) else { return .fullResync() }
    let current = try encodeToken(library.currentChangeToken)
    var changed = Set<String>()
    var deleted = Set<String>()
    do {
      let result = try library.fetchPersistentChanges(since: token)
      var detailsError: Error?
      result.enumerateChanges { change, stop in
        do {
          let details = try change.changeDetails(for: .asset)
          changed.formUnion(details.insertedLocalIdentifiers)
          changed.formUnion(details.updatedLocalIdentifiers)
          deleted.formUnion(details.deletedLocalIdentifiers)
          if changed.count + deleted.count > Limits.maxChanges { stop.pointee = true }
        } catch {
          detailsError = error
          stop.pointee = true
        }
      }
      if let detailsError { throw detailsError }
    } catch let error as PHPhotosError
      where error.code == .persistentChangeTokenExpired
      || error.code == .persistentChangeDetailsUnavailable
    {
      return .fullResync()
    } catch {
      throw HelperError(.internal, "Could not read the Photos change history.")
    }
    if changed.count + deleted.count > Limits.maxChanges { return .fullResync() }

    changed.subtract(deleted)
    var items: [ClientMediaItem] = []
    var found = Set<String>()
    if !changed.isEmpty {
      PHAsset.fetchAssets(withLocalIdentifiers: Array(changed), options: nil).enumerateObjects {
        asset, _, _ in
        found.insert(asset.localIdentifier)
        if let item = makeItem(for: asset) { items.append(item) }
      }
    }
    // Assets that vanished between the history read and the fetch count as deleted.
    deleted.formUnion(changed.subtracting(found))
    items.sort { $0.externalId < $1.externalId }
    return ChangesOutput(
      token: current, changed: items, deleted: deleted.sorted(), fullResyncRequired: false)
  }

  private func encodeToken(_ token: PHPersistentChangeToken) throws -> String {
    guard
      let data = try? NSKeyedArchiver.archivedData(withRootObject: token, requiringSecureCoding: true)
    else { throw HelperError(.internal, "Could not encode the Photos change token.") }
    return base64URLEncode(data)
  }

  private func decodeToken(_ value: String) -> PHPersistentChangeToken? {
    guard let data = base64URLDecode(value) else { return nil }
    return try? NSKeyedUnarchiver.unarchivedObject(ofClass: PHPersistentChangeToken.self, from: data)
  }
}

/// Builds the contract item. Returns nil for media types Media Studio does not handle
/// and for identifiers longer than the contract allows.
func makeItem(for asset: PHAsset) -> ClientMediaItem? {
  let kind: ClientMediaItem.Kind
  switch asset.mediaType {
  case .video: kind = .video
  case .image: kind = asset.mediaSubtypes.contains(.photoLive) ? .livePhoto : .photo
  default: return nil
  }
  guard asset.localIdentifier.utf16.count <= Limits.externalId else { return nil }
  var albums: [String] = []
  PHAssetCollection.fetchAssetCollectionsContaining(asset, with: .album, options: nil)
    .enumerateObjects { collection, _, stop in
      if let title = collection.localizedTitle { albums.append(title) }
      if albums.count >= Limits.albumCount { stop.pointee = true }
    }
  let coordinate = asset.location?.coordinate
  return ClientMediaItem(
    externalId: asset.localIdentifier,
    kind: kind,
    capturedAt: asset.creationDate,
    durationSeconds: kind == .video ? asset.duration : nil,
    width: asset.pixelWidth,
    height: asset.pixelHeight,
    latitude: coordinate?.latitude,
    longitude: coordinate?.longitude,
    albumNames: albums,
    isFavorite: asset.isFavorite,
    fileName: originalResource(for: asset, variant: .original)?.originalFilename)
}

/// The resource holding the untouched original: the video track for videos, the still
/// for photos and Live Photos (the paired motion clip is not exported).
func originalResource(for asset: PHAsset, variant: ExportVariant) -> PHAssetResource? {
  let resources = PHAssetResource.assetResources(for: asset)
  let preferred: [PHAssetResourceType]
  switch (asset.mediaType, variant) {
  case (.video, .original): preferred = [.video, .fullSizeVideo]
  case (.video, .proxy): preferred = [.fullSizeVideo, .video]
  case (_, .original): preferred = [.photo, .fullSizePhoto]
  case (_, .proxy): preferred = [.fullSizePhoto, .photo]
  }
  for type in preferred {
    if let match = resources.first(where: { $0.type == type }) { return match }
  }
  return nil
}

func resourceTypeName(_ type: PHAssetResourceType) -> String {
  switch type {
  case .photo: return "photo"
  case .video: return "video"
  case .audio: return "audio"
  case .alternatePhoto: return "alternate_photo"
  case .fullSizePhoto: return "full_size_photo"
  case .fullSizeVideo: return "full_size_video"
  case .adjustmentData: return "adjustment_data"
  case .adjustmentBasePhoto: return "adjustment_base_photo"
  case .pairedVideo: return "paired_video"
  case .fullSizePairedVideo: return "full_size_paired_video"
  case .adjustmentBasePairedVideo: return "adjustment_base_paired_video"
  case .adjustmentBaseVideo: return "adjustment_base_video"
  @unknown default: return "other"
  }
}