asconnect-service/README.md

# App Store Connect Service (ASConnectService)

A Swift client library for the App Store Connect API, generated from the official OpenAPI specification.

## 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).

## Installation

Add `ASConnectService` as a dependency in your `Package.swift` file:

```swift
dependencies: [
    .package(url: "https://github.com/rock-n-code/asconnect-service.git", from: "2.0.0")
]
```

Then add it to your target dependencies:

```swift
.target(
    name: "YourTarget",
    dependencies: [
        "ASConnectService"
    ]
)
```

## Usage

### 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 `links.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() }
]
```

## Requirements

- Swift 6.0+ (Xcode 16+)
- iOS 14.0+
- macOS 11.0+
- tvOS 14.0+
- visionOS 1.0+
- watchOS 7.0+

## Development

### Building

```bash
make lib-build
```

### Testing

```bash
make lib-test
```

### Generating Documentation

```bash
# Generate documentation archive (for Xcode)
make doc-generate-archive

# Generate documentation for static hosting (e.g. GitHub Pages)
make doc-generate-github

# Preview documentation locally in Safari
make doc-preview

# Check the catalog covers the generated code
make doc-check
```

### Updating the API

The generated code is committed in `Sources/ASConnectService/Sources/Public/Generated`, so consumers don't run the generator.

```bash
# Update to the latest specification
make oas-download

# Regenerate the code only
make oas-generate

# Validate the specification only
make oas-validate
```

## Dependencies

- [swift-openapi-runtime](https://github.com/apple/swift-openapi-runtime)
- [swift-openapi-urlsession](https://github.com/apple/swift-openapi-urlsession)

Development only:

- [swift-openapi-generator](https://github.com/apple/swift-openapi-generator), in `Tools`
- [swift-docc-plugin](https://github.com/swiftlang/swift-docc-plugin)

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

## Contributing

See [CONTRIBUTORS](CONTRIBUTORS) for the list of project authors.