Moved the Amiibo API implementation to its own package (#2)

This PR contains the work done to migrate the *almost* completed**Amiibo API** implementation done in another project to its own stand-alone package.

Reviewed-on: #2
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

CONTRIBUTORS

@@ -0,0 +1,14 @@
+For the purpose of tracking copyright, this is the list of individuals and
+organizations who have contributed source code to this Swift package.
+
+For employees of an organization/company where the copyright of work done
+by employees of that company is held by the company itself, only the company
+needs to be listed here.
+
+## COPYRIGHT HOLDERS
+
+- Röck+Cöde VoF. (all contributors with '@rock-n-code.com')
+
+## PROJECT AUTHORS
+
+- Javier Cicchelli <javier@rock-n-code.com>

Makefile

@@ -1,3 +1,15 @@
+# ===----------------------------------------------------------------------===
+# 
+# This source file is part of the AmiiboAPI open source project
+# 
+# Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+# Licensed under the EUPL 1.2 or later.
+# 
+# See LICENSE for license information
+# See CONTRIBUTORS for the list of AmiiboAPI project authors
+# 
+# ===----------------------------------------------------------------------===
+
 # ENVIRONMENT VARIABLES
 
 environment ?= .env

Package.swift

@@ -1,9 +1,28 @@
 // swift-tools-version: 5.9
 
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
 import PackageDescription
 
 let package = Package(
     name: AmiiboAPI.package,
+    platforms: [
+        .iOS(.v13),
+        .macOS(.v10_15),
+        .tvOS(.v13),
+        .visionOS(.v1),
+        .watchOS(.v6)
+    ],
     products: [
         .library(
             name: AmiiboAPI.package,
@@ -12,10 +31,40 @@ let package = Package(
             ]
         )
     ],
+    dependencies: [
+        .package(
+            url: "https://github.com/apple/swift-openapi-generator.git",
+            from: "1.3.0"
+        ),
+        .package(
+            url: "https://github.com/apple/swift-openapi-runtime",
+            from: "1.5.0"
+        ),
+        .package(
+            url: "https://github.com/apple/swift-openapi-urlsession",
+            from: "1.0.2"
+        )
+    ],
     targets: [
         .target(
             name: AmiiboAPI.target,
-            path: "Sources"
+            dependencies: [
+                .product(
+                    name: "OpenAPIRuntime",
+                    package: "swift-openapi-runtime"
+                ),
+                .product(
+                    name: "OpenAPIURLSession",
+                    package: "swift-openapi-urlsession"
+                )
+            ],
+            path: "Sources",
+            plugins: [
+                .plugin(
+                    name: "OpenAPIGenerator",
+                    package: "swift-openapi-generator"
+                ),
+            ]
         ),
         .testTarget(
             name: AmiiboAPI.test,

Sources/Internal/Extensions/Client+Properties.swift

@@ -0,0 +1,29 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+import OpenAPIURLSession
+
+extension Client {
+    
+    // MARK: Constants
+    
+    static var live: Client {
+        get throws {
+            .init(
+                serverURL: try Servers.server1(),
+                configuration: .init(dateTranscoder: ISODateTranscoder()),
+                transport: URLSessionTransport()
+            )
+        }
+    }
+    
+}

Sources/Internal/Extensions/DateFormatter+Properties.swift

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+import Foundation
+
+extension DateFormatter {
+    
+    static var isoDateTime: DateFormatter {
+        let formatter = DateFormatter()
+        
+        formatter.dateFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSSSS"
+        formatter.timeZone = .init(secondsFromGMT: 0)
+        
+        return formatter
+    }
+    
+}

Sources/Internal/Protocols/APIClient.swift

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+import Foundation
+
+public protocol APIClient {
+    
+    // MARK: Functions
+    
+    func getAmiibos(by filter: AmiiboFilter) async throws -> [Amiibo]
+    func getAmiiboSeries(by filter: AmiiboSeriesFilter) async throws -> [AmiiboSeries]
+    func getAmiiboTypes(by filter: AmiiboTypeFilter) async throws -> [AmiiboType]
+    func getGameCharacters(by filter: GameCharacterFilter) async throws -> [GameCharacter]
+    func getGameSeries(by filter: GameSeriesFilter) async throws -> [GameSeries]
+    func getLastUpdated() async throws -> Date
+    
+}

Sources/Internal/Protocols/KeyNameFilter.swift

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+protocol KeyNameFilter {
+    
+    // MARK: Properties
+    
+    var key: String? { get }
+    var name: String? { get }
+    
+    // MARK: Initialisers
+    
+    init()
+    init(key: String)
+    init(name: String)
+    
+}

Sources/Internal/Protocols/KeyNameModel.swift

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+protocol KeyNameModel: Sendable {
+    
+    // MARK: Properties
+    
+    var key: String { get }
+    var name: String { get }
+    
+    // MARK: Initialisers
+    
+    init(_ payload: Components.Schemas.Tuple)
+    
+}

Sources/Internal/Transcoders/ISODateTranscoder.swift

@@ -0,0 +1,31 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+import Foundation
+import OpenAPIRuntime
+
+struct ISODateTranscoder: DateTranscoder {
+
+    // MARK: Properties
+    private let dateFormatter: DateFormatter = .isoDateTime
+    
+    // MARK: Functions
+    
+    func encode(_ date: Date) throws -> String {
+        dateFormatter.string(from: date)
+    }
+    
+    func decode(_ string: String) throws -> Date {
+        dateFormatter.date(from: string) ?? .init()
+    }
+    
+}

Sources/Public/Clients/AmiiboLiveClient.swift

@@ -0,0 +1,248 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+import Foundation
+import OpenAPIRuntime
+import OpenAPIURLSession
+
+public struct AmiiboLiveClient {
+    
+    // MARK: Properties
+    
+    private let client: Client
+    
+    // MARK: Initialisers
+    
+    public init() throws {
+        self.client = .init(
+            serverURL: try Servers.server1(),
+            configuration: .init(dateTranscoder: ISODateTranscoder()),
+            transport: URLSessionTransport()
+        )
+    }
+    
+}
+
+// MARK: - APIProtocol
+
+extension AmiiboLiveClient: APIClient {
+
+    // MARK: Functions
+    
+    public func getAmiibos(by filter: AmiiboFilter) async throws -> [Amiibo] {
+        let response = try await {
+            do {
+                return try await client.getAmiibos(
+                    .init(query: .init(
+                        amiiboSeries: filter.series,
+                        character: filter.gameCharacter,
+                        gameseries: filter.gameSeries,
+                        id: filter.identifier,
+                        name: filter.name,
+                        showgames: filter.showGames,
+                        showusage: filter.showUsage,
+                        _type: filter.type
+                    ))
+                )
+            } catch let error as ClientError {
+                guard let _ = error.underlyingError as? DecodingError else {
+                    throw AmiiboServiceError.unknown
+                }
+
+                throw AmiiboServiceError.decoding
+            } catch {
+                throw AmiiboServiceError.unknown
+            }
+        }()
+
+        switch response {
+        case let .ok(ok):
+            switch ok.body {
+            case let .json(output):
+                return map(output)
+            }
+            
+        case .badRequest:
+            throw AmiiboServiceError.badRequest
+            
+        case let .undocumented(statusCode, _):
+            throw AmiiboServiceError.undocumented(statusCode)
+        }
+    }
+    
+    public func getAmiiboSeries(by filter: AmiiboSeriesFilter) async throws -> [AmiiboSeries] {
+        let response = try await client.getAmiiboSeries(
+            .init(query: .init(
+                key: filter.key,
+                name: filter.name
+            ))
+        )
+        
+        switch response {
+        case let .ok(ok):
+            switch ok.body {
+            case let .json(output):
+                return map(output, as: AmiiboSeries.self)
+            }
+            
+        case .badRequest:
+            throw AmiiboServiceError.badRequest
+            
+        case .internalServerError:
+            throw AmiiboServiceError.notAvailable
+            
+        case .notFound:
+            throw AmiiboServiceError.notFound
+            
+        case let .undocumented(statusCode, _):
+            throw AmiiboServiceError.undocumented(statusCode)
+        }
+    }
+    
+    public func getAmiiboTypes(by filter: AmiiboTypeFilter) async throws -> [AmiiboType] {
+        let response = try await client.getAmiiboTypes(
+            .init(query: .init(
+                key: filter.key,
+                name: filter.name
+            ))
+        )
+        
+        switch response {
+        case let .ok(ok):
+            switch ok.body {
+            case let .json(output):
+                return map(output, as: AmiiboType.self)
+            }
+            
+        case .badRequest:
+            throw AmiiboServiceError.badRequest
+            
+        case .internalServerError:
+            throw AmiiboServiceError.notAvailable
+            
+        case .notFound:
+            throw AmiiboServiceError.notFound
+            
+        case let .undocumented(statusCode, _):
+            throw AmiiboServiceError.undocumented(statusCode)
+        }
+    }
+    
+    public func getGameCharacters(by filter: GameCharacterFilter) async throws -> [GameCharacter] {
+        let response = try await client.getGameCharacters(
+            .init(query: .init(
+                key: filter.key,
+                name: filter.name
+            ))
+        )
+        
+        switch response {
+        case let .ok(ok):
+            switch ok.body {
+            case let .json(output):
+                return map(output, as: GameCharacter.self)
+            }
+            
+        case .badRequest:
+            throw AmiiboServiceError.badRequest
+            
+        case .internalServerError:
+            throw AmiiboServiceError.notAvailable
+            
+        case .notFound:
+            throw AmiiboServiceError.notFound
+            
+        case let .undocumented(statusCode, _):
+            throw AmiiboServiceError.undocumented(statusCode)
+        }
+    }
+    
+    public func getGameSeries(by filter: GameSeriesFilter) async throws -> [GameSeries] {
+        let response = try await client.getGameSeries(
+            .init(query: .init(
+                key: filter.key,
+                name: filter.name
+            ))
+        )
+        
+        switch response {
+        case let .ok(ok):
+            switch ok.body {
+            case let .json(output):
+                return map(output, as: GameSeries.self)
+            }
+            
+        case .badRequest:
+            throw AmiiboServiceError.badRequest
+            
+        case .internalServerError:
+            throw AmiiboServiceError.notAvailable
+            
+        case .notFound:
+            throw AmiiboServiceError.notFound
+            
+        case let .undocumented(statusCode, _):
+            throw AmiiboServiceError.undocumented(statusCode)
+        }
+    }
+    
+    public func getLastUpdated() async throws -> Date {
+        let response = try await client.getLastUpdated()
+        
+        switch response {
+        case let .ok(ok):
+            switch ok.body {
+            case let .json(output):
+                return output.lastUpdated
+            }
+            
+        case let .undocumented(statusCode, _):
+            throw AmiiboServiceError.undocumented(statusCode)
+        }
+    }
+    
+}
+
+// MARK: - Helpers
+
+private extension AmiiboLiveClient {
+    
+    // MARK: Functions
+    
+    func map(_ wrapper: Components.Schemas.AmiiboWrapper) -> [Amiibo] {
+        switch wrapper.amiibo {
+        case let .Amiibo(object):
+            return [.init(object)]
+            
+        case let .AmiiboList(list):
+            return list
+                .map { .init($0) }
+                .sorted { $0.identifier < $1.identifier }
+        }
+    }
+    
+    func map<Model: KeyNameModel>(
+        _ wrapper: Components.Schemas.TupleWrapper,
+        as: Model.Type
+    ) -> [Model] {
+        switch wrapper.amiibo {
+        case let .Tuple(payload):
+            return [.init(payload)]
+            
+        case let .TupleList(list):
+            return list
+                .map { .init($0) }
+                .sorted { $0.key < $1.key }
+        }
+    }
+    
+}

Sources/Public/Clients/AmiiboMockClient.swift

@@ -0,0 +1,130 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+import Foundation
+
+public struct AmiiboMockClient {
+    
+    // MARK: Properties
+    
+    private let amiibos: [Amiibo]?
+    private let amiiboSeries: [AmiiboSeries]?
+    private let amiiboTypes: [AmiiboType]?
+    private let error: AmiiboServiceError?
+    private let gameCharacters: [GameCharacter]?
+    private let gameSeries: [GameSeries]?
+    private let lastUpdated: Date?
+    
+    // MARK: Initialisers
+    
+    public init(
+        amiibos: [Amiibo]? = nil,
+        amiiboSeries: [AmiiboSeries]? = nil,
+        amiiboTypes: [AmiiboType]? = nil,
+        gameCharacters: [GameCharacter]? = nil,
+        gameSeries: [GameSeries]? = nil,
+        lastUpdated: Date? = nil,
+        error: AmiiboServiceError? = nil
+    ) {
+        self.amiibos = amiibos
+        self.amiiboSeries = amiiboSeries
+        self.amiiboTypes = amiiboTypes
+        self.error = error
+        self.gameCharacters = gameCharacters
+        self.gameSeries = gameSeries
+        self.lastUpdated = lastUpdated
+    }
+    
+}
+
+// MARK: - APIClient
+
+extension AmiiboMockClient: APIClient {
+    
+    // MARK: Functions
+
+    public func getAmiibos(by filter: AmiiboFilter) async throws -> [Amiibo] {
+        try throwErrorIfExists()
+
+        guard let amiibos else {
+            throw AmiiboServiceError.notFound
+        }
+        
+        return amiibos
+    }
+    
+    public func getAmiiboSeries(by filter: AmiiboSeriesFilter) async throws -> [AmiiboSeries] {
+        try throwErrorIfExists()
+
+        guard let amiiboSeries else {
+            throw AmiiboServiceError.notFound
+        }
+        
+        return amiiboSeries
+    }
+    
+    public func getAmiiboTypes(by filter: AmiiboTypeFilter) async throws -> [AmiiboType] {
+        try throwErrorIfExists()
+
+        guard let amiiboTypes else {
+            throw AmiiboServiceError.notFound
+        }
+        
+        return amiiboTypes
+    }
+    
+    public func getGameCharacters(by filter: GameCharacterFilter) async throws -> [GameCharacter] {
+        try throwErrorIfExists()
+
+        guard let gameCharacters else {
+            throw AmiiboServiceError.notFound
+        }
+        
+        return gameCharacters
+    }
+    
+    public func getGameSeries(by filter: GameSeriesFilter) async throws -> [GameSeries] {
+        try throwErrorIfExists()
+
+        guard let gameSeries else {
+            throw AmiiboServiceError.notFound
+        }
+        
+        return gameSeries
+    }
+    
+    public func getLastUpdated() async throws -> Date {
+        try throwErrorIfExists()
+
+        guard let lastUpdated else {
+            throw AmiiboServiceError.notFound
+        }
+        
+        return lastUpdated
+    }
+    
+    
+}
+
+// MARK: - Helpers
+
+private extension AmiiboMockClient {
+    
+    // MARK: Functions
+    
+    func throwErrorIfExists() throws {
+        if let error {
+            throw error
+        }
+    }
+    
+}

Sources/Public/Errors/AmiiboServiceError.swift

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public enum AmiiboServiceError: Error {
+    case badRequest
+    case decoding
+    case notAvailable
+    case notFound
+    case undocumented(_ statusCode: Int)
+    case unknown
+}
+
+// MARK: - Equatable
+
+extension AmiiboServiceError: Equatable {}

Sources/Public/Filters/AmiiboFilter.swift

@@ -0,0 +1,48 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public struct AmiiboFilter {
+    
+    // MARK: Properties
+    
+    public let gameCharacter: String?
+    public let gameSeries: String?
+    public let identifier: String?
+    public let name: String?
+    public let series: String?
+    public let showGames: Bool?
+    public let showUsage: Bool?
+    public let type: String?
+    
+    // MARK: Initialisers
+    
+    public init(
+        identifier: String? = nil,
+        name: String? = nil,
+        type: String? = nil,
+        series: String? = nil,
+        gameCharacter: String? = nil,
+        gameSeries: String? = nil,
+        showGames: Bool? = nil,
+        showUsage: Bool? = nil
+    ) {
+        self.gameCharacter = gameCharacter
+        self.gameSeries = gameSeries
+        self.identifier = identifier
+        self.name = name
+        self.series = series
+        self.showGames = showGames
+        self.showUsage = showUsage
+        self.type = type
+    }
+
+}

Sources/Public/Filters/AmiiboSeriesFilter.swift

@@ -0,0 +1,37 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public struct AmiiboSeriesFilter: KeyNameFilter {
+    
+    // MARK: Properties
+    
+    public let key: String?
+    public let name: String?
+    
+    // MARK: Initialisers
+    
+    public init() {
+        self.key = nil
+        self.name = nil
+    }
+    
+    public init(key: String) {
+        self.key = key
+        self.name = nil
+    }
+    
+    public init(name: String) {
+        self.key = nil
+        self.name = name
+    }
+    
+}

Sources/Public/Filters/AmiiboTypeFilter.swift

@@ -0,0 +1,37 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public struct AmiiboTypeFilter: KeyNameFilter {
+
+    // MARK: Properties
+    
+    public let key: String?
+    public let name: String?
+    
+    // MARK: Initialisers
+    
+    public init() {
+        self.key = nil
+        self.name = nil
+    }
+    
+    public init(key: String) {
+        self.key = key
+        self.name = nil
+    }
+    
+    public init(name: String) {
+        self.key = nil
+        self.name = name
+    }
+    
+}

Sources/Public/Filters/GameCharacterFilter.swift

@@ -0,0 +1,37 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public struct GameCharacterFilter: KeyNameFilter {
+    
+    // MARK: Properties
+    
+    public let key: String?
+    public let name: String?
+    
+    // MARK: Initialisers
+    
+    public init() {
+        self.key = nil
+        self.name = nil
+    }
+    
+    public init(key: String) {
+        self.key = key
+        self.name = nil
+    }
+    
+    public init(name: String) {
+        self.key = nil
+        self.name = name
+    }
+    
+}

Sources/Public/Filters/GameSeriesFilter.swift

@@ -0,0 +1,37 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public struct GameSeriesFilter: KeyNameFilter {
+    
+    // MARK: Properties
+    
+    public let key: String?
+    public let name: String?
+    
+    // MARK: Initialisers
+    
+    public init() {
+        self.key = nil
+        self.name = nil
+    }
+    
+    public init(key: String) {
+        self.key = key
+        self.name = nil
+    }
+    
+    public init(name: String) {
+        self.key = nil
+        self.name = name
+    }
+    
+}

Sources/Public/Models/Amiibo.swift

@@ -0,0 +1,59 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+import Foundation
+
+public struct Amiibo: Sendable {
+    
+    // MARK: Properties
+    
+    public let gameCharacter: String
+    public let gameSeries: String
+    public let head: String
+    public let image: String
+    public let name: String
+    public let platform: Platform?
+    public let release: Release
+    public let series: String
+    public let tail: String
+    public let type: String
+    
+    // MARK: Initialisers
+
+    init(_ payload: Components.Schemas.Amiibo) {
+        self.gameCharacter = payload.character
+        self.gameSeries = payload.gameSeries
+        self.head = payload.head
+        self.image = payload.image
+        self.name = payload.name
+        self.platform = .init(
+            payload.gamesSwitch,
+            payload.games3DS,
+            payload.gamesWiiU
+        )
+        self.release = .init(payload.release)
+        self.series = payload.amiiboSeries
+        self.tail = payload.tail
+        self.type = payload._type
+    }
+    
+    // MARK: Computed
+    
+    public var identifier: String {
+        head + tail
+    }
+    
+    public var imageURL: URL? {
+        .init(string: image)
+    }
+
+}

Sources/Public/Models/Amiibo/Amiibo+Game.swift

@@ -0,0 +1,37 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+extension Amiibo {
+    public struct Game: Sendable {
+        
+        // MARK: Properties
+        
+        public let identifiers: [String]
+        public let name: String
+        public let usages: [Usage]?
+        
+        // MARK: Initialisers
+        
+        init(_ payload: Components.Schemas.AmiiboGame) {
+            self.identifiers = payload.gameID
+            self.name = payload.gameName
+            self.usages = {
+                guard let usages = payload.amiiboUsage else {
+                    return nil
+                }
+                
+                return usages.map { .init($0) }
+            }()
+        }
+        
+    }
+}

Sources/Public/Models/Amiibo/Amiibo+Platform.swift

@@ -0,0 +1,51 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+extension Amiibo {
+    public struct Platform: Sendable {
+        
+        // MARK: Properties
+        
+        public let `switch`: [Game]
+        public let threeDS: [Game]
+        public let wiiU: [Game]
+        
+        // MARK: Initialisers
+        
+        init?(
+            _ `switch`: [Components.Schemas.AmiiboGame]?,
+            _ threeDS: [Components.Schemas.AmiiboGame]?,
+            _ wiiU: [Components.Schemas.AmiiboGame]?
+        ) {
+            guard (`switch` != nil && `switch`?.isEmpty == false)
+                    || (threeDS != nil && threeDS?.isEmpty == false)
+                    || (wiiU != nil && wiiU?.isEmpty == false)
+            else {
+                return nil
+            }
+            
+            self.switch = {
+                guard let `switch` else { return [] }
+                return `switch`.map { .init($0) }
+            }()
+            self.threeDS = {
+                guard let threeDS else { return [] }
+                return threeDS.map { .init($0) }
+            }()
+            self.wiiU = {
+                guard let wiiU else { return [] }
+                return wiiU.map { .init($0) }
+            }()
+        }
+
+    }
+}

Sources/Public/Models/Amiibo/Amiibo+Release.swift

@@ -0,0 +1,35 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+import Foundation
+
+extension Amiibo {
+    public struct Release: Sendable {
+        
+        // MARK: Properties
+        
+        public let america: Date?
+        public let australia: Date?
+        public let europe: Date?
+        public let japan: Date?
+        
+        // MARK: Initialisers
+        
+        init(_ payload: Components.Schemas.AmiiboRelease) {
+            self.america = payload.na
+            self.australia = payload.au
+            self.europe = payload.eu
+            self.japan = payload.jp
+        }
+        
+    }
+}

Sources/Public/Models/Amiibo/Amiibo+Usage.swift

@@ -0,0 +1,29 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+extension Amiibo {
+    public struct Usage: Sendable {
+        
+        // MARK: Properties
+        
+        public let explanation: String
+        public let isWriteable: Bool
+        
+        // MARK: Initialisers
+        
+        init(_ payload: Components.Schemas.AmiiboUsage) {
+            self.explanation = payload.Usage
+            self.isWriteable = payload.write
+        }
+        
+    }
+}

Sources/Public/Models/AmiiboSeries.swift

@@ -0,0 +1,27 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public struct AmiiboSeries: KeyNameModel {
+    
+    // MARK: Properties
+    
+    public let key: String
+    public let name: String
+    
+    // MARK: Initialisers
+    
+    init(_ payload: Components.Schemas.Tuple) {
+        self.key = payload.key
+        self.name = payload.name
+    }
+    
+}

Sources/Public/Models/AmiiboType.swift

@@ -0,0 +1,27 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public struct AmiiboType: KeyNameModel {
+    
+    // MARK: Properties
+    
+    public let key: String
+    public let name: String
+    
+    // MARK: Initialisers
+    
+    init(_ payload: Components.Schemas.Tuple) {
+        self.key = payload.key
+        self.name = payload.name
+    }
+    
+}

Sources/Public/Models/GameCharacter.swift

@@ -0,0 +1,27 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public struct GameCharacter: KeyNameModel {
+    
+    // MARK: Properties
+    
+    public let key: String
+    public let name: String
+    
+    // MARK: Initialisers
+    
+    init(_ payload: Components.Schemas.Tuple) {
+        self.key = payload.key
+        self.name = payload.name
+    }
+    
+}

Sources/Public/Models/GameSeries.swift

@@ -0,0 +1,27 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+public struct GameSeries: KeyNameModel {
+    
+    // MARK: Properties
+    
+    public let key: String
+    public let name: String
+    
+    // MARK: Initialisers
+    
+    init(_ payload: Components.Schemas.Tuple) {
+        self.key = payload.key
+        self.name = payload.name
+    }
+    
+}

Sources/Public/Services/AmiiboService.swift

@@ -0,0 +1,63 @@
+//===----------------------------------------------------------------------===
+//
+// This source file is part of the AmiiboAPI open source project
+//
+// Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of AmiiboAPI project authors
+//
+//===----------------------------------------------------------------------===
+
+import Foundation
+
+public struct AmiiboService {
+    
+    // MARK: Properties
+    
+    private let client: any APIClient
+    
+    // MARK: Initialisers
+
+    public init(_ client: any APIClient) {
+        self.client = client
+    }
+
+    // MARK: Functions
+    
+    public func getAmiibos(
+        _ filter: AmiiboFilter = .init()
+    ) async throws -> [Amiibo] {
+        try await client.getAmiibos(by: filter)
+    }
+    
+    public func getAmiiboSeries(
+        _ filter: AmiiboSeriesFilter = .init()
+    ) async throws -> [AmiiboSeries] {
+        try await client.getAmiiboSeries(by: filter)
+    }
+    
+    public func getAmiiboTypes(
+        _ filter: AmiiboTypeFilter = .init()
+    ) async throws -> [AmiiboType] {
+        try await client.getAmiiboTypes(by: filter)
+    }
+    
+    public func getGameCharacters(
+        _ filter: GameCharacterFilter = .init()
+    ) async throws -> [GameCharacter] {
+        try await client.getGameCharacters(by: filter)
+    }
+    
+    public func getGameSeries(
+        _ filter: GameSeriesFilter = .init()
+    ) async throws -> [GameSeries] {
+        try await client.getGameSeries(by: filter)
+    }
+    
+    public func getLastUpdated() async throws -> Date {
+        try await client.getLastUpdated()
+    }
+    
+}

Sources/amiibo_api.swift

@@ -1,2 +0,0 @@
-// The Swift Programming Language
-// https://docs.swift.org/swift-book

Sources/openapi-generator-config.yaml

@@ -0,0 +1,16 @@
+# ===----------------------------------------------------------------------===
+# 
+# This source file is part of the AmiiboAPI open source project
+# 
+# Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+# Licensed under the EUPL 1.2 or later.
+# 
+# See LICENSE for license information
+# See CONTRIBUTORS for the list of AmiiboAPI project authors
+# 
+# ===----------------------------------------------------------------------===
+
+generate:
+  - types
+  - client
+accessModifier: internal

Sources/openapi.yaml

@@ -0,0 +1,376 @@
+# ===----------------------------------------------------------------------===
+# 
+# This source file is part of the AmiiboAPI open source project
+# 
+# Copyright (c) 2024 Röck+Cöde VoF. and the AmiiboAPI project authors
+# Licensed under the EUPL 1.2 or later.
+# 
+# See LICENSE for license information
+# See CONTRIBUTORS for the list of AmiiboAPI project authors
+# 
+# ===----------------------------------------------------------------------===
+
+openapi: '3.1.0'
+info:
+  title: Amiibo API service
+  description: The Amiibo API RESTful service.
+  version: 1.0.0
+servers:
+  - url: https://www.amiiboapi.com/api
+    description: Amiibo API service (live)
+paths:
+  /amiibo:
+    get:
+      description: Get a list of all the Amiibo items available in the database.
+      operationId: getAmiibos
+      responses:
+        '200':
+          description: Successful response returning the object that contains a list of Amiibo items.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AmiiboWrapper'
+        '400':
+          description: Bad Amiibo request.
+      parameters:
+        - name: amiiboSeries
+          in: query
+          description: The Amiibo series identifier or name to filter the response.
+          required: false
+          schema:
+            type: string
+          style: form
+        - name: character
+          in: query
+          description: The game character identifier or name to filter the response.
+          required: false
+          schema:
+            type: string
+          style: form
+        - name: gameseries
+          in: query
+          description: The game series identifier or name to filter the response.
+          required: false
+          schema:
+            type: string
+          style: form
+        - name: id
+          in: query
+          description: The Amiibo identifier to filter the response.
+          required: false
+          schema:
+            type: string
+          style: form
+        - name: name
+          in: query
+          description: The Amiibo name to filter the response.
+          required: false
+          schema:
+            type: string
+          style: form
+        - name: showgames
+          in: query
+          description: The flag that indicates whether to include information about related games.
+          required: false
+          schema:
+            type: boolean
+          style: form
+        - name: showusage
+          in: query
+          description: The flag that indicates whether to include information about Amiibo usage in related games.
+          required: false
+          schema:
+            type: boolean
+          style: form
+        - name: type
+          in: query
+          description: The Amiibo type to filter the response.
+          required: false
+          schema:
+            type: string
+          style: form
+
+  /amiiboseries:
+    get:
+      description: Get a list of all the Amiibo series available in the database.
+      operationId: getAmiiboSeries
+      responses:
+        '200':
+          description: Successful response returning the object that contains a list of Amiibo series.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TupleWrapper'
+        '400':
+          description: Bad Amiibo series request.
+        '404':
+          description: Amiibo series not found.
+        '500':
+          description: Service currently not available.
+    parameters:
+      - name: key
+        in: query
+        description: The Amiibo series key to filter the response.
+        required: false
+        schema:
+          type: string
+        style: form
+      - name: name
+        in: query
+        description: The Amiibo series name to filter the response.
+        required: false
+        schema:
+          type: string
+        style: form
+
+  /character:
+    get:
+      description: Get a list of all the game characters available in the database.
+      operationId: getGameCharacters
+      responses:
+        '200':
+          description: Successful response returning the object that contains a list of game characters.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TupleWrapper'
+        '400':
+          description: Bad game character request.
+        '404':
+          description: Game character not found.
+        '500':
+          description: Service currently not available.
+    parameters:
+      - name: key
+        in: query
+        description: The game character key to filter the response.
+        required: false
+        schema:
+          type: string
+        style: form
+      - name: name
+        in: query
+        description: The game character name to filter the response.
+        required: false
+        schema:
+          type: string
+        style: form
+
+  /gameseries:
+    get:
+      description: Gets a list of all the game series available in the database.
+      operationId: getGameSeries
+      responses:
+        '200':
+          description: Successful response returning the object that contains a list of game series.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TupleWrapper'
+        '400':
+          description: Bad game series request.
+        '404':
+          description: Game series not found.
+        '500':
+          description: Service currently not available.
+    parameters:
+      - name: key
+        in: query
+        description: The game series key to filter the response.
+        required: false
+        schema:
+          type: string
+        style: form
+      - name: name
+        in: query
+        description: The game series name to filter the response.
+        required: false
+        schema:
+          type: string
+        style: form
+
+  /type:
+    get:
+      description: Gets a list of all the Amiibo types available in the database.
+      operationId: getAmiiboTypes
+      responses:
+        '200':
+          description: Successful response returning the object that contains a list of Amiibo types.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TupleWrapper'
+        '400':
+          description: Bad Amiibo type request.
+        '404':
+          description: Amiibo type not found.
+        '500':
+          description: Service currently not available.
+    parameters:
+      - name: key
+        in: query
+        description: The Amiibo type key to filter the response.
+        required: false
+        schema:
+          type: string
+        style: form
+      - name: name
+        in: query
+        description: The Amiibo type name to filter the response.
+        required: false
+        schema:
+          type: string
+        style: form
+
+  /lastupdated:
+    get:
+      description: Gets a timestamp when the Amiibo data was last updated.
+      operationId: getLastUpdated
+      responses:
+        '200':
+          description: Successful response returning the object that contains the date and time when the database was last updated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LastUpdated'
+
+components:
+  schemas:
+    Amiibo:
+      type: object
+      properties:
+        amiiboSeries:
+          type: string
+        character:
+          type: string
+        gameSeries:
+          type: string
+        games3DS:
+          type: array
+          items:
+            $ref: '#/components/schemas/AmiiboGame'
+        gamesSwitch:
+          type: array
+          items:
+            $ref: '#/components/schemas/AmiiboGame'
+        gamesWiiU:
+          type: array
+          items:
+            $ref: '#/components/schemas/AmiiboGame'
+        head:
+          type: string
+        image:
+          type: string
+        name:
+          type: string
+        release:
+          type: object
+          $ref: '#/components/schemas/AmiiboRelease'
+        tail:
+          type: string
+        type:
+          type: string
+      required:
+        - amiiboSeries
+        - character
+        - gameSeries
+        - head
+        - image
+        - name
+        - release
+        - tail
+        - type
+
+    AmiiboGame:
+      type: object
+      properties:
+        amiiboUsage:
+          type: array
+          items:
+            $ref: '#/components/schemas/AmiiboUsage'
+        gameID:
+          type: array
+          items:
+            type: string
+        gameName:
+          type: string
+      required:
+        - gameID
+        - gameName
+
+    AmiiboList:
+      type: array
+      items:
+        $ref: '#/components/schemas/Amiibo'
+
+    AmiiboRelease:
+      type: object
+      properties:
+        au:
+          type: string
+          format: date-time
+        eu:
+          type: string
+          format: date-time
+        jp:
+          type: string
+          format: date-time
+        na:
+          type: string
+          format: date-time
+
+    AmiiboUsage:
+      type: object
+      properties:
+        Usage:
+          type: string
+        write:
+          type: boolean
+      required:
+        - Usage
+        - write
+
+    AmiiboWrapper:
+      type: object
+      properties:
+        amiibo:
+          oneOf:
+            - $ref: '#/components/schemas/Amiibo'
+            - $ref: '#/components/schemas/AmiiboList'
+      required:
+        - amiibo
+
+    LastUpdated:
+      type: object
+      properties:
+        lastUpdated:
+          type: string
+          format: date-time
+      required:
+        - lastUpdated
+
+    Tuple:
+      type: object
+      properties:
+        key:
+          type: string
+        name:
+          type: string
+      required:
+        - key
+        - name
+
+    TupleList:
+      type: array
+      items:
+        $ref: '#/components/schemas/Tuple'
+
+    TupleWrapper:
+      type: object
+      properties:
+        amiibo:
+          oneOf:
+            - $ref: '#/components/schemas/Tuple'
+            - $ref: '#/components/schemas/TupleList'
+      required:
+        - amiibo

Tests/amiibo_apiTests.swift

@@ -1,7 +0,0 @@
-import Testing
-
-@testable import AmiiboAPI
-
-@Test func example() async throws {
-    // Write your test here and use APIs like `#expect(...)` to check expected conditions.
-}