asconnect-service/Sources/ASConnectService/Catalogs/ASConnectService.docc/Library.md

# ``ASConnectService``

A type-safe Swift client for the App Store Connect API.

## Overview

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`` 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.url(),
    transport: URLSessionTransport(),
    middlewares: [
        BearerAuthMiddleware { try await tokenProvider.token() }
    ]
)
```

To use a token you signed yourself, pass it directly. It expires after 20 minutes at most:

```swift
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

### API Client

- ``Client``
- ``APIProtocol``

### Authentication

- ``BearerAuthMiddleware``
- ``APIKeyTokenProvider``

### Pagination

- ``PagedSequence``

### Rate Limiting

- ``RateLimitMiddleware``

### Generated Types

- ``Components``
- ``Operations``
- ``Servers``