Overhauled the library with several new features (#5)

## Summary

Updates the library to v4.5.1 of the App Store Connect API, and ships it as a breaking 2.0.0 release with pagination, API key authentication, rate limiting, and a lighter install for consumers.

## Breaking changes

- **Minimum platforms:** iOS 14, macOS 11, tvOS 14, watchOS 7, and visionOS 1.
- **Toolchain:** Swift 6.0+ (Xcode 16+). The package builds in the Swift 6 language mode.
- **Runtime:** requires `swift-openapi-runtime` 1.11.0 or later.

## Changes

- **API:** updated the OpenAPI specification to v4.5.1, covering 1,303 operations and 1,473 schemas.
- **Pagination:** the spec patch adds the undocumented `cursor` query parameter to the 465 paged operations. `PagedDocumentLinks.nextCursor` reads the cursor from a page, and `PagedSequence` iterates every page.
- **Authentication:** `APIKeyTokenProvider` signs ES256 tokens from an API key and reuses each one until a minute before it expires. `BearerAuthMiddleware` now accepts a token provider.
- **Rate limiting:** `RateLimitMiddleware` retries `429` responses, waiting for `Retry-After` or backing off exponentially.
- **Generated code:** committed to `Sources/ASConnectService/Sources/Public/Generated` instead of generated by a build plugin. Consumers now resolve 4 packages instead of 12, and Xcode no longer asks to trust a plugin.
- **Tooling:**
  - `make oas-download` now downloads, patches, generates, and checks the docs in one go.
  - New `make oas-generate`, `make oas-validate`, and `make doc-check` targets.
  - The generator is pinned in `Tools/`, and the DocC plugin is only resolved by the documentation targets.
- **Documentation:** the DocC catalog now lists every operation and schema in the spec, and the catalog and README are rewritten for the new APIs.
- **Housekeeping:** Apache 2.0 license headers on every Swift file, including `Package.swift` and the tests.

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

Sources/ASConnectService/Catalogs/ASConnectService.docc/Library.md

@@ -1,36 +1,78 @@
 # ``ASConnectService``
 
-A Swift client library for the App Store Connect API, generated from the official OpenAPI specification.
+A type-safe Swift client for the App Store Connect API.
 
 ## Overview
 
-``ASConnectService`` provides a type-safe, Swift-native interface to Apple's App Store Connect API. This package enables developers to programmatically interact with App Store Connect services for managing apps, builds, reviews, sales reports, and more.
-
-The library is automatically generated from the official App Store Connect API OpenAPI specification using Apple's [swift-openapi-generator](https://github.com/apple/swift-openapi-generator), ensuring complete API coverage and type safety.
+ASConnectService exposes every endpoint of Apple's App Store Connect API as a Swift method with typed requests and responses. It's generated from the official OpenAPI specification with [Swift OpenAPI Generator](https://github.com/apple/swift-openapi-generator).
 
 ### Creating a Client
 
-Create a ``Client`` instance by providing a server URL and transport. Use ``BearerAuthMiddleware`` to authenticate requests with a JSON Web Token (JWT).
+Create a ``Client`` with a server URL, a transport, and a ``BearerAuthMiddleware``. With an API key from App Store Connect, ``APIKeyTokenProvider`` signs the JSON Web Tokens (JWT) the API requires, and renews them before they expire:
 
 ```swift
 import ASConnectService
 import OpenAPIURLSession
 
+let tokenProvider = try APIKeyTokenProvider(
+    issuerID: yourIssuerID,
+    keyID: yourKeyID,
+    privateKey: yourP8FileContents
+)
+
 let client = Client(
-    serverURL: try Servers.server1(),
+    serverURL: try Servers.Server1.url(),
     transport: URLSessionTransport(),
     middlewares: [
-        BearerAuthMiddleware(token: yourJWTToken)
+        BearerAuthMiddleware { try await tokenProvider.token() }
     ]
 )
 ```
 
-### Making API Calls
-
-The ``Client`` conforms to ``APIProtocol``, which defines a method for every endpoint in the App Store Connect API. Each method accepts an `Input` value and returns an `Output` value with the response.
+To use a token you signed yourself, pass it directly. It expires after 20 minutes at most:
 
 ```swift
-let response = try await client.appsGetCollection(.init())
+BearerAuthMiddleware(token: yourJWTToken)
+```
+
+### Making API Calls
+
+Each endpoint is a method on ``Client``, declared by ``APIProtocol``. It returns an `Output` enum with a case for each documented response:
+
+```swift
+let response = try await client.appsGetCollection(query: .init(limit: 10))
+let apps = try response.ok.body.json.data
+```
+
+The `ok` property throws for any other response. To handle those, switch over the `Output` cases, such as `.unauthorized` or `.undocumented(statusCode:_:)`.
+
+### Fetching More Pages
+
+Lists are paged. Iterate a ``PagedSequence`` to fetch each page in turn:
+
+```swift
+let pages = PagedSequence(links: \.links) { cursor in
+    try await client.appsGetCollection(query: .init(limit: 200, cursor: cursor)).ok.body.json
+}
+
+var apps: [Components.Schemas.App] = []
+
+for try await page in pages {
+    apps += page.data
+}
+```
+
+To fetch pages yourself, pass a page's ``Components/Schemas/PagedDocumentLinks/nextCursor`` as the `cursor` of the next request.
+
+### Handling Rate Limits
+
+Add ``RateLimitMiddleware`` before the authentication middleware to retry `429 Too Many Requests` responses:
+
+```swift
+middlewares: [
+    RateLimitMiddleware(),
+    BearerAuthMiddleware { try await tokenProvider.token() }
+]
 ```
 
 ## Topics
@@ -43,6 +85,15 @@ let response = try await client.appsGetCollection(.init())
 ### Authentication
 
 - ``BearerAuthMiddleware``
+- ``APIKeyTokenProvider``
+
+### Pagination
+
+- ``PagedSequence``
+
+### Rate Limiting
+
+- ``RateLimitMiddleware``
 
 ### Generated Types