Improve OpenAPI error handling (#78)

- Make some enums non-exhaustive (closes #77)
  - Also a tentative fix for #62 and #64
- Improve logging on deserialization failure

We now use raw JS to patch the OpenAPI spec instead of openapi-overlay.
It's a lot more flexible this way.

Author: kabiroberai

Makefile

@@ -144,8 +144,8 @@ api: openapi/openapi.json
 update-api:
 	@+$(MAKE) -B api
 
-openapi/openapi.json: openapi/base.json Sources/DeveloperAPI/openapi-overlay.yaml
-	npx --yes bump-cli overlay openapi/base.json Sources/DeveloperAPI/openapi-overlay.yaml > openapi/openapi.json
+openapi/openapi.json: openapi/base.json Sources/DeveloperAPI/patch.js
+	node Sources/DeveloperAPI/patch.js < openapi/base.json > openapi/openapi.json
 
 openapi/base.json:
 	@mkdir -p openapi

Package.swift

@@ -88,7 +88,7 @@ let package = Package(
             dependencies: [
                 .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
             ],
-            exclude: ["openapi-generator-config.yaml", "openapi-overlay.yaml"]
+            exclude: ["openapi-generator-config.yaml", "patch.js"]
         ),
         .target(
             name: "XKit",

Sources/DeveloperAPI/Generated/Types.swift

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+
+function makeOpen(enumSchema) {
+    const copy = structuredClone(enumSchema);
+    Object.keys(enumSchema).forEach(k => delete enumSchema[k]);
+    Object.assign(enumSchema, {
+        anyOf: [
+            copy,
+            { type: 'string' },
+        ]
+    })
+}
+
+function format(schema) {
+    const schemas = schema.components.schemas;
+
+    // this field is required when using the private Xcode API
+    const capabilityCreateRelationships = schemas.BundleIdCapabilityCreateRequest.properties.data.properties.relationships;
+    capabilityCreateRelationships.properties.capability = {
+        type: 'object',
+        properties: {
+            data: {
+                type: 'object',
+                properties: {
+                    type: {
+                        type: 'string',
+                        enum: ['capabilities'],
+                    },
+                    id: { $ref: '#/components/schemas/CapabilityType' },
+                },
+                required: ['id', 'type'],
+            },
+        },
+        required: ['data'],
+    }
+    capabilityCreateRelationships.required.push('capability');
+
+    // we don't use this but it triggers a deprecation warning. see:
+    // https://github.com/apple/swift-openapi-generator/issues/715
+    schemas.App.properties.relationships.properties.inAppPurchases.deprecated = false;
+
+    // openapi-generator expects response enums to be exhaustive. Apple's ASC OpenAPI spec
+    // misses some cases that they do, actually, return.
+    // https://swiftpackageindex.com/apple/swift-openapi-generator/1.7.2/documentation/swift-openapi-generator/useful-openapi-patterns#Open-enums-and-oneOfs
+    makeOpen(schemas.BundleIdPlatform);
+    makeOpen(schemas.CapabilityType);
+    makeOpen(schemas.CertificateType);
+    makeOpen(schemas.Device.properties.attributes.properties.deviceClass);
+
+    return schema;
+}
+
+const text = fs.readFileSync(process.stdin.fd, 'utf8');
+const json = JSON.parse(text);
+const formatted = format(json);
+const formattedText = JSON.stringify(formatted);
+console.log(formattedText);

Sources/DeveloperAPI/openapi-overlay.yaml

@@ -57,7 +57,7 @@ public struct DeveloperServicesAddAppOperation: DeveloperServicesOperation {
                             _type: .bundleIds,
                             attributes: .init(
                                 name: name,
-                                platform: .ios,
+                                platform: .init(.ios),
                                 identifier: newBundleID
                             )
                         )
@@ -105,8 +105,8 @@ public struct DeveloperServicesAddAppOperation: DeveloperServicesOperation {
                 }
             } else {
                 // DeveloperServices doesn't allow deleting these capabilities
-                let requiredCapabilities: Set<Components.Schemas.CapabilityType> = [.inAppPurchase]
-                if let capType = cap.attributes?.capabilityType, !requiredCapabilities.contains(capType) {
+                let requiredCapabilities: Set<Components.Schemas.CapabilityType.Value1Payload> = [.inAppPurchase]
+                if let capType = cap.attributes?.capabilityType?.value1, !requiredCapabilities.contains(capType) {
                     _ = try await context.developerAPIClient
                         .bundleIdCapabilitiesDeleteInstance(path: .init(id: cap.id))
                         .noContent

Sources/DeveloperAPI/patch.js

@@ -15,11 +15,11 @@ public struct DeveloperServicesCapability: Sendable, Hashable {
     public var settings: [Components.Schemas.CapabilitySetting]?
 
     public init(
-        _ capabilityType: Components.Schemas.CapabilityType,
+        _ capabilityType: Components.Schemas.CapabilityType.Value1Payload,
         isFree: Bool,
         settings: [Components.Schemas.CapabilitySetting]? = nil
     ) {
-        self.capabilityType = capabilityType
+        self.capabilityType = .init(capabilityType)
         self.isFree = isFree
         self.settings = settings
     }

Sources/XKit/DeveloperServices/App IDs/DeveloperServicesAddAppOperation.swift

@@ -54,7 +54,7 @@ public struct DeveloperServicesFetchCertificateOperation: DeveloperServicesOpera
                 _type: .certificates,
                 attributes: .init(
                     csrContent: csr.pemString,
-                    certificateType: .development
+                    certificateType: .init(.development)
                 )
             )))
         )

Sources/XKit/DeveloperServices/App IDs/Entitlements/DeveloperServicesCapability.swift

@@ -256,3 +256,27 @@ struct LoggingMiddleware: ClientMiddleware {
         return (response, body)
     }
 }
+
+// syntactic sugar to make it nicer to work with `anyOf:` types
+public protocol OpenAPIExtensibleEnum {
+    associatedtype Value1Payload: RawRepresentable<String>, Codable, Hashable, Sendable, CaseIterable
+    var value1: Value1Payload? { get set }
+    var value2: String? { get set }
+
+    init(value1: Value1Payload?, value2: String?)
+}
+
+extension OpenAPIExtensibleEnum {
+    public var rawValue: String {
+        value2!
+    }
+
+    public init(_ value: Value1Payload) {
+        self.init(value1: value, value2: nil)
+    }
+}
+
+extension Components.Schemas.BundleIdPlatform: OpenAPIExtensibleEnum {}
+extension Components.Schemas.CapabilityType: OpenAPIExtensibleEnum {}
+extension Components.Schemas.CertificateType: OpenAPIExtensibleEnum {}
+extension Components.Schemas.Device.AttributesPayload.DeviceClassPayload: OpenAPIExtensibleEnum {}

Sources/XKit/DeveloperServices/Certificates/DeveloperServicesFetchCertificateOperation.swift

@@ -27,7 +27,7 @@ public struct DeveloperServicesFetchDeviceOperation: DeveloperServicesOperation
                 _type: .devices,
                 attributes: .init(
                     name: self.context.deviceName,
-                    platform: .ios,
+                    platform: .init(.ios),
                     udid: self.context.udid
                 )
             )))