diff --git a/README.md b/README.md index 5634005f5e..b6717c1231 100644 --- a/README.md +++ b/README.md @@ -1 +1,152 @@ # App Store Connect Service (ASConnectService) + +A Swift client library for the App Store Connect API, generated from the official OpenAPI specification. + +## 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`, ensuring complete API coverage and type safety. + +## Key Features + +- **Type-Safe API**: Fully typed requests and responses based on the OpenAPI specification +- **Async/Await Support**: Modern Swift concurrency with `async`/`await` +- **Cross-Platform**: Supports iOS, macOS, tvOS, visionOS, and watchOS +- **Automatic Generation**: Code is generated from the official API specification +- **Comprehensive Coverage**: Access to all App Store Connect API endpoints + +## Installation + +### Swift Package Manager + +Add ``ASConnectService`` as a dependency in your `Package.swift` file: + +```swift +dependencies: [ + .package(url: "https://github.com/rock-n-code/asconnect-service.git", from: "1.0.0") +] +``` + +Then add it to your target dependencies: + +```swift +.target( + name: "YourTarget", + dependencies: [ + "ASConnectService" + ] +) +``` + +## Basic Usage + +```swift +import ASConnectService +import OpenAPIURLSession + +// Create a client with your API key +let client = Client( + serverURL: try Servers.server1(), + transport: URLSessionTransport() +) + +// Make API calls +let apps = try await client.apps_get() +``` + +## Authentication + +The App Store Connect API requires authentication using API keys. You'll need to: + +1. Create an API key in App Store Connect +2. Generate a signed JWT token using your key ID, issuer ID, and private key +3. Inject the token into each request via an OpenAPI middleware + +```swift +import OpenAPIRuntime + +struct BearerAuthMiddleware: ClientMiddleware { + let token: String + + func intercept( + _ request: HTTPRequest, + body: HTTPBody?, + baseURL: URL, + operationID: String, + next: @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?) + ) async throws -> (HTTPResponse, HTTPBody?) { + var request = request + request.headerFields[.authorization] = "Bearer \(token)" + return try await next(request, body, baseURL) + } +} + +let client = Client( + serverURL: try Servers.server1(), + transport: URLSessionTransport(), + middlewares: [BearerAuthMiddleware(token: yourJWTToken)] +) +``` + +## Supported Platforms + +- iOS 13.0+ +- macOS 10.15+ +- tvOS 13.0+ +- visionOS 1.0+ +- watchOS 6.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 +``` + +## Dependencies + +- [swift-openapi-generator](https://github.com/apple/swift-openapi-generator) +- [swift-openapi-runtime](https://github.com/apple/swift-openapi-runtime) +- [swift-openapi-urlsession](https://github.com/apple/swift-openapi-urlsession) +- [swift-docc-plugin](https://github.com/swiftlang/swift-docc-plugin) + +## License + +Licensed under the Apache License, Version 2.0. See LICENSE file for details. + +## Contributing + +See CONTRIBUTORS file for the list of project authors. + +## API Coverage + +The package provides access to all App Store Connect API endpoints including: + +- Apps and app management +- Builds and beta testing +- App Store reviews and ratings +- Sales and financial reports +- User and role management +- In-app purchases and subscriptions +- And many more... diff --git a/Sources/ASConnectService/Catalogs/ASConnectService.docc/Library.md b/Sources/ASConnectService/Catalogs/ASConnectService.docc/Library.md index 6ea5d20d1b..56df742bcf 100644 --- a/Sources/ASConnectService/Catalogs/ASConnectService.docc/Library.md +++ b/Sources/ASConnectService/Catalogs/ASConnectService.docc/Library.md @@ -1,13 +1,129 @@ # ``ASConnectService`` -Summary +A Swift client library for the App Store Connect API, generated from the official OpenAPI specification. ## Overview -Text +``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`, ensuring complete API coverage and type safety. + +## Key Features + +- **Type-Safe API**: Fully typed requests and responses based on the OpenAPI specification +- **Async/Await Support**: Modern Swift concurrency with `async`/`await` +- **Cross-Platform**: Supports iOS, macOS, tvOS, visionOS, and watchOS +- **Automatic Generation**: Code is generated from the official API specification +- **Comprehensive Coverage**: Access to all App Store Connect API endpoints + +## 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: "1.0.0") +] +``` + +Then add it to your target dependencies: + +```swift +.target( + name: "YourTarget", + dependencies: [ + "ASConnectService" + ] +) +``` + +## Basic Usage + +```swift +import ASConnectService +import OpenAPIURLSession + +// Create a client with your API key +let client = Client( + serverURL: try Servers.server1(), + transport: URLSessionTransport() +) + +// Make API calls +let apps = try await client.apps_get() +``` + +## Authentication + +The App Store Connect API requires authentication using API keys. You'll need to: + +1. Create an API key in App Store Connect +2. Generate a signed JWT token using your key ID, issuer ID, and private key +3. Inject the token into each request via an OpenAPI middleware + +```swift +import OpenAPIRuntime + +struct BearerAuthMiddleware: ClientMiddleware { + let token: String + + func intercept( + _ request: HTTPRequest, + body: HTTPBody?, + baseURL: URL, + operationID: String, + next: @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?) + ) async throws -> (HTTPResponse, HTTPBody?) { + var request = request + request.headerFields[.authorization] = "Bearer \(token)" + return try await next(request, body, baseURL) + } +} + +let client = Client( + serverURL: try Servers.server1(), + transport: URLSessionTransport(), + middlewares: [BearerAuthMiddleware(token: yourJWTToken)] +) +``` + +## Supported Platforms + +- iOS 13.0+ +- macOS 10.15+ +- tvOS 13.0+ +- visionOS 1.0+ +- watchOS 6.0+ + +## Dependencies + +- [swift-openapi-generator](https://github.com/apple/swift-openapi-generator) +- [swift-openapi-runtime](https://github.com/apple/swift-openapi-runtime) +- [swift-openapi-urlsession](https://github.com/apple/swift-openapi-urlsession) +- [swift-docc-plugin](https://github.com/swiftlang/swift-docc-plugin) ## Topics -### Group +### Getting Started -- ``Symbol`` +- ``Client``: The main API client for making requests + +### API Endpoints + +The package provides access to all App Store Connect API endpoints including: + +- Apps and app management +- Builds and beta testing +- App Store reviews and ratings +- Sales and financial reports +- User and role management +- In-app purchases and subscriptions +- And many more... + +### Error Handling + +All API calls can throw errors that conform to the OpenAPI specification. Handle errors appropriately in your application code. + +## License + +Licensed under the Apache License, Version 2.0. See LICENSE file for details.