javier
13b9c74a38
CI / Build and test (push) Canceled after 0s
Documentation / Build documentation (push) Canceled after 0s
Documentation / Deploy to GitHub Pages (push) Canceled after 0s
This PR contains the work done to fix a cancellation-mapping bug in `AmiiboLiveClient`, bring the client under offline test coverage, add the conformances SwiftUI and persistence need, and moves CI and documentation publishing to GitHub Actions. All public API changes are additive.
### Fix
- `AmiiboLiveClient` reported an early task cancellation as `.unknown("CancellationError()")`. The OpenAPI runtime wraps every error in `ClientError`, so the `CancellationError` check never matched; it now also checks the wrapped error and throws `.cancelled`.
### Tests
- `ThrowingTransport` and `StubTransport` test doubles let the live client run offline. New tests cover error mapping, HTTP status → error mapping, `oneOf` object-vs-list decoding, `"amiibo": null`, sorting, filter → query encoding, `Platform`/`Release` mapping, and the date transcoder.
- Models gained `package` memberwise initializers so tests can build real fixtures without `@testable`. These are not public API.
- The test target now depends on `OpenAPIRuntime` and `HTTPTypes` (both already in the dependency graph).
### API
- Models are `Codable` and `Identifiable` (`Amiibo.id` is its `identifier`; the key/name models use `key`).
- Filters are `Hashable`.
### Documentation
- Doc comments trimmed library-wide; one repeated `- Throws:` sentence appeared 24 times. `Library.md` and the README tightened to match.
### CI and docs publishing
- `ci.yml`: build and offline tests on PRs and pushes to `main`.
- `live-tests.yml`: weekly and on-demand run against the live API.
- `docs.yml`: builds DocC on PRs, deploys to GitHub Pages on `main`. Pinned to Xcode 26 because swift-docc-plugin 1.5.0 fails to launch its tools under Xcode 27.
- The generated `docs/` folder (327 files) is removed from the repository and ignored.
Reviewed-on: #31
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
139 lines
4.0 KiB
Markdown
139 lines
4.0 KiB
Markdown
[](https://swiftpackageindex.com/rock-n-code/amiibo-service)
|
||
[](https://swiftpackageindex.com/rock-n-code/amiibo-service)
|
||
[](https://github.com/rock-n-code/amiibo-service/actions/workflows/ci.yml)
|
||
|
||
# Amiibo Service
|
||
|
||
A Swift client for the [Amiibo API](https://www.amiiboapi.org).
|
||
|
||
## Requirements
|
||
|
||
- Swift 6.2 or later
|
||
- iOS 13, macOS 10.15, tvOS 13, visionOS 1, or watchOS 6 or later
|
||
|
||
## Installation
|
||
|
||
Add the package and the `AmiiboService` product to `Package.swift`:
|
||
|
||
```swift
|
||
let package = Package(
|
||
// name, platforms, products, etc.
|
||
dependencies: [
|
||
.package(url: "https://github.com/rock-n-code/amiibo-service", from: "2.0.0"),
|
||
],
|
||
targets: [
|
||
.target(
|
||
name: "SomeTarget",
|
||
dependencies: [
|
||
.product(name: "AmiiboService", package: "amiibo-service"),
|
||
]
|
||
),
|
||
]
|
||
)
|
||
```
|
||
|
||
In Xcode, add the package URL under **File › Add Package Dependencies…**.
|
||
|
||
## Usage
|
||
|
||
```swift
|
||
import AmiiboService
|
||
|
||
let service = AmiiboService()
|
||
|
||
// All amiibos
|
||
let amiibos = try await service.getAmiibos()
|
||
|
||
// Amiibos whose name contains "zelda"
|
||
let zeldaAmiibos = try await service.getAmiibos(.init(name: "zelda"))
|
||
|
||
// Amiibo series, types, game characters, and game series
|
||
let series = try await service.getAmiiboSeries()
|
||
let types = try await service.getAmiiboTypes()
|
||
let characters = try await service.getGameCharacters()
|
||
let gameSeries = try await service.getGameSeries()
|
||
|
||
// Date of the last data update (UTC)
|
||
let lastUpdated = try await service.getLastUpdated()
|
||
```
|
||
|
||
Results are sorted in ascending order by identifier (amiibos) or key (everything else). Models are `Hashable`, `Codable`, and `Identifiable`; filters are `Hashable`.
|
||
|
||
## Error handling
|
||
|
||
Every call throws `AmiiboServiceError`. When nothing matches, `getAmiibos(_:)` returns an empty array, while the other list calls throw `AmiiboServiceError.notFound`:
|
||
|
||
```swift
|
||
do throws(AmiiboServiceError) {
|
||
let series = try await service.getAmiiboSeries(.init(key: "0x01"))
|
||
} catch .notFound {
|
||
// No amiibo series has this key.
|
||
} catch {
|
||
// .badRequest, .cancelled, .decoding, .notAvailable, .undocumented, or .unknown
|
||
}
|
||
```
|
||
|
||
## Caching
|
||
|
||
The library has no built-in cache. The Amiibo API asks regular consumers to cache responses. To do that, give `AmiiboLiveClient` a transport backed by a `URLCache`:
|
||
|
||
```swift
|
||
import OpenAPIURLSession
|
||
|
||
let configuration = URLSessionConfiguration.default
|
||
|
||
configuration.urlCache = URLCache(
|
||
memoryCapacity: 5_000_000,
|
||
diskCapacity: 50_000_000
|
||
)
|
||
|
||
let transport = URLSessionTransport(
|
||
configuration: .init(
|
||
session: URLSession(configuration: configuration)
|
||
)
|
||
)
|
||
|
||
let service = AmiiboService(
|
||
client: AmiiboLiveClient(transport: transport)
|
||
)
|
||
```
|
||
|
||
## Testing
|
||
|
||
To test without network access, pass a mock `AmiiboClient` to `AmiiboService(client:)`. `AmiiboClient` refines `Sendable`, so the mock must be `Sendable`, too:
|
||
|
||
```swift
|
||
import AmiiboService
|
||
|
||
struct MockClient: AmiiboClient {
|
||
var error: AmiiboServiceError?
|
||
|
||
func getAmiibos(
|
||
by filter: AmiiboFilter
|
||
) async throws(AmiiboServiceError) -> [Amiibo] {
|
||
if let error { throw error }
|
||
return []
|
||
}
|
||
|
||
// Implement the remaining requirements...
|
||
}
|
||
|
||
let service = AmiiboService(client: MockClient())
|
||
```
|
||
|
||
## Development
|
||
|
||
Run `make` to list the available tasks for building, testing, and generating documentation.
|
||
|
||
The test suite runs offline by default. Tests against the live service run only if `AMIIBO_LIVE_TESTS` is set to `1`:
|
||
|
||
```shell
|
||
AMIIBO_LIVE_TESTS=1 swift test
|
||
```
|
||
|
||
In Xcode, set the variable in the scheme's **Test** action.
|
||
|
||
## Documentation
|
||
|
||
See the [online documentation](https://rock-n-code.github.io/amiibo-service/documentation/amiiboservice/).
|