README.md

@@ -3,11 +3,11 @@
 
 # Amiibo Service
 
-A library written entirely with [Swift](https://www.swift.org) that provides everything the developer needs to interacts with the [Amiibo API](https://www.amiiboapi.org) backend service.
+A library written entirely with [Swift](https://www.swift.org) that provides everything the developer needs to interact with the [Amiibo API](https://www.amiiboapi.org) backend service.
 
 ## Installation
 
-To use this library, then it is mandatory to add it as a dependency in the `Package.swift` file:
+To use this library, add it as a dependency in the `Package.swift` file:
 
 ```swift
 let package = Package(
@@ -28,10 +28,82 @@ let package = Package(
 )
 ```
 
-It is also possible to use this library with your app in Xcode, then add it as a dependency in your Xcode project.
+It is also possible to use this library with your app in Xcode by adding it as a dependency in your Xcode project.
 
-> important: Swift 5.10 or higher is required in order to build this library.
+> [!IMPORTANT]
+> Swift 5.10 or higher is required in order to build this library.
+
+## Usage
+
+```swift
+import AmiiboService
+
+let service = AmiiboService()
+
+// Fetch all amiibos
+let amiibos = try await service.getAmiibos()
+
+// Fetch amiibos filtered by name
+let zeldaAmiibos = try await service.getAmiibos(.init(name: "zelda"))
+
+// Fetch 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()
+
+// Fetch the last updated timestamp
+let lastUpdated = try await service.getLastUpdated()
+```
+
+## Caching
+
+The [Amiibo API](https://www.amiiboapi.org) recommends that consumers who call the API regularly implement caching on their systems. Pass a custom `URLSessionTransport` with a cache-configured `URLSession` to `AmiiboLiveClient`:
+
+```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
+
+The `AmiiboClient` protocol enables creating custom mock clients for unit testing without network calls. Conform to `AmiiboClient` and inject it into `AmiiboService` via its `init(client:)` initializer:
+
+```swift
+import AmiiboService
+
+struct MyMockClient: AmiiboClient {
+    var error: AmiiboServiceError?
+
+    func getAmiibos(
+        by filter: AmiiboFilter
+    ) async throws(AmiiboServiceError) -> [Amiibo] {
+        if let error { throw error }
+        return []
+    }
+
+    // Implement remaining protocol requirements...
+}
+
+let service = AmiiboService(client: MyMockClient())
+```
 
 ## Documentation
 
-Please refer to the [online documentation](https://rock-n-code.github.io/amiibo-service/documentation/amiiboservice/) for further informations about this library.
+Please refer to the [online documentation](https://rock-n-code.github.io/amiibo-service/documentation/amiiboservice/) for further information about this library.

Sources/AmiiboService/Catalogs/AmiiboService.docc/Extensions/AmiiboService.md

@@ -0,0 +1,22 @@
+# ``AmiiboService``
+
+## Topics
+
+### Initializers
+
+- ``AmiiboService/init(client:)``
+
+### Amiibo endpoints
+
+- ``AmiiboService/getAmiibos(_:)``
+- ``AmiiboService/getAmiiboSeries(_:)``
+- ``AmiiboService/getAmiiboTypes(_:)``
+
+### Game endpoints
+
+- ``AmiiboService/getGameCharacters(_:)``
+- ``AmiiboService/getGameSeries(_:)``
+
+### System endpoints
+
+- ``AmiiboService/getLastUpdated()``

Sources/AmiiboService/Catalogs/AmiiboService.docc/Extensions/AmiiboServiceError.md

@@ -0,0 +1,19 @@
+# ``AmiiboServiceError``
+
+## Topics
+
+### Request errors
+
+- ``AmiiboServiceError/badRequest``
+- ``AmiiboServiceError/cancelled``
+
+### Response errors
+
+- ``AmiiboServiceError/decoding``
+- ``AmiiboServiceError/notFound``
+
+### Service errors
+
+- ``AmiiboServiceError/notAvailable``
+- ``AmiiboServiceError/undocumented(_:)``
+- ``AmiiboServiceError/unknown``

Sources/AmiiboService/Catalogs/AmiiboService.docc/Library.md

@@ -72,6 +72,31 @@ This leverages HTTP cache headers from the server and persists cached responses
 
 Alternatively, cache the results returned by ``AmiiboService`` directly in your application using any storage mechanism that fits your needs, such as an in-memory dictionary, a database, or a file-based store.
 
+## Testing
+
+The ``AmiiboClient`` protocol enables creating custom mock clients for testing, eliminating the need for network calls in unit tests. Conform to ``AmiiboClient`` and return stubbed data or throw ``AmiiboServiceError`` errors to verify your application's behavior:
+
+```swift
+import AmiiboService
+
+struct MyMockClient: AmiiboClient {
+    var error: AmiiboServiceError?
+
+    func getAmiibos(
+        by filter: AmiiboFilter
+    ) async throws(AmiiboServiceError) -> [Amiibo] {
+        if let error { throw error }
+        return []
+    }
+
+    // Implement remaining protocol requirements...
+}
+
+let service = AmiiboService(client: MyMockClient())
+```
+
+Inject the mock client into ``AmiiboService`` via its ``AmiiboService/init(client:)`` initializer to test how your code handles empty results, specific errors, or any other scenario without relying on the live backend.
+
 ## Tasks
 
 This library offers a set of ready-to-use tasks that simplify the interaction with the library, which the developer can use from any `Terminal` application.