Rework endpoints and naming

Author: marcprux

Sources/FairExpo/AltStoreCatalog.swift

@@ -90,16 +90,18 @@ public struct AltCatalogAppItem : Codable, Equatable {
     public var subtitle: String?
     /// A full-length description of your app. This can include any information you believe is relevant for your app, such as feature descriptions or additional links.
     public var localizedDescription: String?
-    /// Undocumented, but used by
-    public var _localizedDescription: [String: String]?
+    /// Undocumented, e.g.: `{ "en": "English description", "fr": "Description en français" }`
+    public var _localizedDescriptions: [String: String]?
     /// A link to you app's icon image. It will automatically be masked to an app icon shape.
     public var iconURL: String?
     /// The color used to theme your app's store page. We recommend using your app's existing tint color (if it has one), but you are free to choose any color you want.
     public var tintColor: String?
     /// The store category best representing your app.
-    public var category: String?
+    public var category: AltStoreCategory?
     /// Screenshots of your app. We recommend showcasing your app's main features.
     public var screenshots: ScreenshotCollection?
+    /// Undocumented
+    public var beta: Bool?
     /// A list of all the published versions of your app.
     public var versions: [AltCatalogAppItemVersion]?
     /// An object listing all entitlements and privacy permissions information used by the app.
@@ -112,7 +114,7 @@ public struct AltCatalogAppItem : Codable, Equatable {
     public typealias ScreenshotCollection = Either<[ScreenshotChoice]>.Or<[String: [ScreenshotChoice]]>
     public typealias ScreenshotChoice = Either<String>.Or<AppScreenshot>
 
-    public init(name: String, bundleIdentifier: String? = nil, marketplaceID: String? = nil, developerName: String? = nil, subtitle: String? = nil, localizedDescription: String? = nil, iconURL: String? = nil, tintColor: String? = nil, category: String? = nil, screenshots: ScreenshotCollection? = nil, versions: [AltCatalogAppItemVersion]? = nil, appPermissions: AltCatalogAppItemPermissions? = nil, patreon: AltCatalogAppItemPatreon? = nil) {
+    public init(name: String, bundleIdentifier: String? = nil, marketplaceID: String? = nil, developerName: String? = nil, subtitle: String? = nil, localizedDescription: String? = nil, iconURL: String? = nil, tintColor: String? = nil, category: AltStoreCategory? = nil, screenshots: ScreenshotCollection? = nil, versions: [AltCatalogAppItemVersion]? = nil, appPermissions: AltCatalogAppItemPermissions? = nil, patreon: AltCatalogAppItemPatreon? = nil) {
         self.name = name
         self.bundleIdentifier = bundleIdentifier
         self.marketplaceID = marketplaceID
@@ -129,6 +131,37 @@ public struct AltCatalogAppItem : Codable, Equatable {
     }
 }
 
+/// The store category best representing your app. One of: `developer`, `entertainment`, `games`, `lifestyle`, `other`, `photo-video`, `social`, `utilities`
+///
+/// https://faq.altstore.io/developers/make-a-source#category-string
+public struct AltStoreCategory : Codable, Equatable, RawRepresentable, CaseIterable {
+    public static let developer = AltStoreCategory(rawValue: "developer")
+    public static let entertainment = AltStoreCategory(rawValue: "entertainment")
+    public static let games = AltStoreCategory(rawValue: "games")
+    public static let lifestyle = AltStoreCategory(rawValue: "lifestyle")
+    public static let other = AltStoreCategory(rawValue: "other")
+    public static let photoVideo = AltStoreCategory(rawValue: "photo-video")
+    public static let social = AltStoreCategory(rawValue: "social")
+    public static let utilities = AltStoreCategory(rawValue: "utilities")
+
+    public static var allCases: [AltStoreCategory] = [
+        .developer,
+        .entertainment,
+        .games,
+        .lifestyle,
+        .other,
+        .photoVideo,
+        .social,
+        .utilities,
+    ]
+
+    public var rawValue: String
+
+    public init(rawValue: String) {
+        self.rawValue = rawValue
+    }
+}
+
 /// https://faq.altstore.io/developers/make-a-source#screenshots
 public struct AppScreenshot : Codable, Equatable {
     public var imageURL: String

Sources/FairExpo/AppCatalogAPI.swift

@@ -1,6 +1,44 @@
 import Foundation
 import FairCore
 
+extension AppCatalogIndex {
+    public static let appfairCatalogURL: URL! = URL(string: "https://appfair.net/appfair-apps.json")
+}
+
+
+/// The master list of apps and configuration for an app catalog.
+///
+/// This merely includes fundamental pointers to the app's location, like the app name and token and bundleID/appid.
+/// The remainder of the metadata will be fetched from the specific catalog (e.g., `altstore.json`, `fdroid.json`)
+/// attached to individual releases.
+///
+/// See: https://appfair.net/appfair-apps.json
+public struct AppCatalogIndex : Decodable {
+    public var catalogs: Catalogs
+    public var apps: [App]
+
+    public struct Catalogs : Decodable {
+        public var altstore: AltCatalog?
+        public var fdroid: FDroidIndex.Repo?
+    }
+
+    public struct App : Decodable {
+        public var token: String // e.g., "Skip-Notes"
+        public var ios: DarwinApp?
+        public var android: AndroidApp?
+
+        public struct DarwinApp : Decodable {
+            public var bundleId: String
+            public var appleItemId: String?
+        }
+
+        public struct AndroidApp : Decodable {
+            public var appid: String
+        }
+    }
+}
+
+
 extension Plist {
     /// A map of all the "*UsageDescription*" properties that have string values
     var usageDescriptions: [String: String] {
@@ -144,8 +182,6 @@ public struct LocalizedStringsFile {
     }
 }
 
-
-
 /// https://docs.fastlane.tools/actions/deliver/#available-metadata-folder-options
 public struct AppMetadata : Codable {
     // Non-Localized Metadata

Sources/FairExpo/FDroidCatalog.swift

@@ -154,6 +154,8 @@ public struct FDroidIndex : Codable, Equatable {
     }
 
     /// A categorization of an app (e.g, "Connectivity", "Development", "Games", "Graphics", "Internet", "Money", "Multimedia", "Navigation", "Phone & SMS", "Reading", "Science & Education", "Security", "Sports & Health", "System", "Theming", "Time", "Writing")
+    ///
+    /// e.g., see the list at https://gitlab.com/fdroid/fdroiddata/-/blob/master/config/categories.yml
     public struct Category : Codable, Equatable {
         public var icon: LocalizedFile?
         public var name: LocalizedText?

Sources/FairExpo/FairSeal.swift

@@ -5,10 +5,10 @@ import FairCore
 public enum FairGround {
     /// A fairground that uses hosted git repository with a REST API,
     /// such as github.com
-    case hub(FairHub)
+    case hub(GitHubEndpointService)
 
-    /// The `FairHub` for repositories that use that model
-    public var hub: FairHub? {
+    /// The `GitHubEndpointService` for repositories that use that model
+    public var hub: GitHubEndpointService? {
         switch self {
         case .hub(let x): return x
         }

Sources/FairExpo/HubAPI.swift …ces/FairExpo/GitHubEndpointService.swiftSources/FairExpo/HubAPI.swift renamed to Sources/FairExpo/GitHubEndpointService.swift Sources/FairExpo/HubAPI.swift renamed to Sources/FairExpo/GitHubEndpointService.swift

@@ -10,8 +10,11 @@ public let appfairName = "appfair"
 
 public let appfairRoot = URL(string: "https://appfair.net")!
 
+@available(*, deprecated, renamed: "GitHubEndpointService")
+public typealias FairHub = GitHubEndpointService
+
 /// A Fair Ground based on an online git service such as GitHub or GitLab.
-public struct FairHub : GraphQLEndpointService {
+public struct GitHubEndpointService : GraphQLEndpointService {
     /// The root of the FairGround-compatible service
     public var baseURL: URL
 
@@ -34,7 +37,7 @@ public struct FairHub : GraphQLEndpointService {
     /// 502 sometimes happens with large responses
     public static var backoffCodes: IndexSet { IndexSet([403, 502]) }
 
-    public typealias BaseFork = FairHub.CatalogForksQuery.QueryResponse.BaseRepository.Repository
+    public typealias BaseFork = CatalogForksQuery.QueryResponse.BaseRepository.Repository
 
     /// The FairHub is initialized with a host identifier (e.g., "github.com/appfair") that corresponds to the hub being used.
     public init(hostOrg: String, authToken: String? = nil, fairsealIssuer: String?, fairsealKey: Data?, requestRetryCount: Int) throws {
@@ -76,7 +79,7 @@ public struct ArtifactTarget : Codable, Hashable {
     }
 }
 
-extension FairHub {
+extension GitHubEndpointService {
     public struct ProjectConfiguration {
         /// The regular expression patterns of allowed app names
         public var allowName: [NSRegularExpression]
@@ -106,7 +109,7 @@ extension FairHub {
         /// Validates that the app name is included in the `allow-name` patterns and not included in the `deny-name` list of expressions.
         public func validateAppName(_ name: String?) throws {
             guard let name = name, try permitted(value: name, allow: allowName, deny: denyName) == true else {
-                throw FairHub.Errors.invalidName(name)
+                throw Errors.invalidName(name)
             }
         }
 
@@ -118,14 +121,14 @@ extension FairHub {
             // if we specified an allow list, then at least one of the patterns must match the email
             if !allow.isEmpty {
                 guard let _ = allow.first(where: matches) else {
-                    throw FairHub.Errors.valueNotAllowed(value)
+                    throw Errors.valueNotAllowed(value)
                 }
             }
 
             // conversely, if we specified a deny list, then all the addresses must not match
             if !deny.isEmpty {
                 if let _ = deny.first(where: matches) {
-                    throw FairHub.Errors.valueDenied(value)
+                    throw Errors.valueDenied(value)
                 }
             }
 
@@ -144,7 +147,7 @@ extension FairHub {
     public func buildFundingSources(owner: String, baseRepository: String) async throws -> [AppFundingSource] {
         var sources: [AppFundingSource] = []
 
-        func createSponsor(from sponsor: FairHub.GetSponsorsQuery.QueryResponse.Repository.SponsorsListing, url: URL) -> AppFundingSource {
+        func createSponsor(from sponsor: GetSponsorsQuery.QueryResponse.Repository.SponsorsListing, url: URL) -> AppFundingSource {
             var goals: [AppFundingSource.FundingGoal] = []
             if let activeGoal = sponsor.activeGoal,
                 let goalKind = activeGoal.kind?.rawValue {
@@ -282,7 +285,7 @@ extension FairHub {
         let nameWithOwner = appOrg + "/" + baseRepository
 
         let prid = try await fetchPRID()
-        func fetchPRID() async throws -> FairHub.OID {
+        func fetchPRID() async throws -> GitHubEndpointService.OID {
             if let issueNumber = issueNumber {
                 // the issue number was explicitly specified; look up the PR issue by number
                 return try await self.request(LookupPRNumberQuery(owner: owner, name: baseRepository, prid: issueNumber)).get().data.repository.pullRequest.id