@W-16589742: [iOS] REST wrappers for select SFAP APIs

[JohnsonEricAtSalesforce]

🎸 Ready For Final Review 🥁

This adds REST API clients for select sfap_api endpoints to match the Android version in forcedotcom/SalesforceMobileSDK-Android#2644

Here's a sample of how this can be used in detail.

    /// The generation id from the `sfap_api` `generations` endpoint
    private var generationId: String? = nil
    
    /**
     * Fetches generated text from the `sfap_api` "generations" endpoint.
     */
    private func generateText() async {
        do {
            guard
                let userAccountCurrent = UserAccountManager.shared.currentUserAccount,
                let restClient = RestClient.restClient(for: userAccountCurrent)
            else { return }
            
            // Guards.
            let generationsResponseBody = try await SFapClient(
                apiHostName: "dev.api.salesforce.com",
                modelName: "sfdc_ai__DefaultGPT35Turbo",
                restClient: restClient
            ).fetchGeneratedText(
                "Tell me a story about an action movie hero with really, really cool hair."
            )
            
            self.generationId = generationsResponseBody.generation?.id
            print("SFAP_API-TESTS: \(String(describing: generationsResponseBody.generation?.generatedText))")
            print("SFAP_API-TESTS: \(String(describing: generationsResponseBody.sourceJson))")
            
            // Test submitting feedback for the generated text.
            await submitFeedback()
        } catch let error {
            SFSDKCoreLogger().e(
                SFapClient.classForCoder(),
                message: "Cannot fetch generated text due to an error with message '\(error.localizedDescription)'.")
        }
    }
    
    /**
     * Fetches generated chat responses from the `sfap_api` "generations" endpoint.
     */
    private func generateChat() async {
        do {
            guard
                let userAccountCurrent = UserAccountManager.shared.currentUserAccount,
                let restClient = RestClient.restClient(for: userAccountCurrent)
            else { return }
            
            // Guards.
            let chatGenerationsResponseBody = try await SFapClient(
                apiHostName: "dev.api.salesforce.com",
                modelName: "sfdc_ai__DefaultGPT35Turbo",
                restClient: restClient
            ).fetchGeneratedChat(requestBody: MyChatGenerationsRequestBody(
                messages: [
                    ChatGenerationsRequestBody.Message(
                        role: "user",
                        content: "Can you help me clean my kitchen?"
                    )],
                localization : ChatGenerationsRequestBody.Localization(
                    defaultLocale: "en_US",
                    inputLocales: [ChatGenerationsRequestBody.Locale(
                        locale: "en_US",
                        probability: 0.1
                    )],
                    expectedLocales: ["en_US"]
                ),
                /* This is an example of how to provide app-specific values for the `tags` parameter */
                tags : MyChatGenerationsRequestBody.Tags(
                    customProperty: "This property was specified by the app rather than the Salesforce Mobile SDK."
                )
            ))
            
            chatGenerationsResponseBody.generationDetails?.generations?.forEach { generation in
                print("SFAP_API-TESTS: \(String(describing: generation.content))")
            }
            print("SFAP_API-TESTS: \(String(describing: chatGenerationsResponseBody.sourceJson))")
        } catch let error {
            SFSDKCoreLogger().e(
                SFapClient.classForCoder(),
                message: "Cannot fetch generated chat responses due to an error with message '\(error.localizedDescription)'.")
        }
    }
    
    /**
     * Submits feedback for previously generated text from the `sfap_api`
     * endpoints to the `sfap_api` `feedback` endpoint.
     * @return Job The Kotlin Coroutines Job running the submission
     */
    private func submitFeedback() async {
        do {
            guard
                let userAccountCurrent = UserAccountManager.shared.currentUserAccount,
                let restClient = RestClient.restClient(for: userAccountCurrent)
            else { return }
            
            // Guards.
            let feedbackResponseBody = try await SFapClient(
                apiHostName: "dev.api.salesforce.com",
                restClient: restClient
            ).submitGeneratedTextFeedback(requestBody: FeedbackRequestBody(
                feedback: "GOOD",
                generationId: generationId
            ))
            
            print("SFAP_API-TESTS: \(String(describing: feedbackResponseBody.message))")
            print("SFAP_API-TESTS: \(String(describing: feedbackResponseBody.sourceJson))")
        } catch let error {
            SFSDKCoreLogger().e(
                SFapClient.classForCoder(),
                message: "Cannot fetch generated chat responses due to an error with message '\(error.localizedDescription)'.")
        }
    }
    
    /**
     * Fetches generated embeddings from the `sfap_api` "embeddings" endpoint.
     * @return Job The Kotlin Coroutines Job running the fetch
     */
    private func generateEmbeddings() async {
        
        do {
            guard
                let userAccountCurrent = UserAccountManager.shared.currentUserAccount,
                let restClient = RestClient.restClient(for: userAccountCurrent)
            else { return }
            
            // Guards.
            let embeddingsResponseBody = try await SFapClient(
                apiHostName: "dev.api.salesforce.com",
                modelName: "sfdc_ai__DefaultOpenAITextEmbeddingAda_002",
                restClient: restClient
            ).fetchGeneratedEmbeddings(requestBody: EmbeddingsRequestBody(
                input: ["Please clean up after yourself"]
            ))
            
            embeddingsResponseBody.embeddings?.forEach{ embedding in
                print("SFAP_API-TESTS: \(String(describing: embedding.embedding))")
            }
            print("SFAP_API-TESTS: \(String(describing: embeddingsResponseBody.sourceJson))")
        } catch let error {
            SFSDKCoreLogger().e(
                SFapClient.classForCoder(),
                message: "Cannot fetch generated embeddings due to an error with message '\(error.localizedDescription)'.")
        }
    }
    
    public class MyChatGenerationsRequestBody : ChatGenerationsRequestBody {
        
        required init(from decoder: any Decoder) throws {
            let container = try decoder.container(keyedBy: CodingKeys.self)
            self.tags = try container.decode(Tags.self, forKey: .tags)
            try super.init(from: decoder)
        }

        public init(
            messages: Array<ChatGenerationsRequestBody.Message>,
            localization: ChatGenerationsRequestBody.Localization,
            tags: Tags
        ) {
            self.tags = tags
            super.init(
                messages: messages,
                localization: localization
            )
        }
        
        public override func encode(to encoder: any Encoder) throws {
            var container = encoder.container(keyedBy: CodingKeys.self)
            try container.encode(tags, forKey: .tags)
            try super.encode(to: encoder)
        }
        
        public let tags: Tags?
        
        enum CodingKeys: String, CodingKey {
            case tags = "tags"
        }
        
        public struct Tags: Codable {
            let customProperty: String
            
            enum CodingKeys: String, CodingKey {
                case customProperty = "custom_property"
            }
        }
    }

[JohnsonEricAtSalesforce]

@bbirman - Here's a commit with all your items from last night. Thanks so much for the extra eyes 🤘🏻

[bbirman]

Whoops, sorry, I didn't mean to suggest changing the SFAP part of the Swift names, I meant that I think all the objc names should match across classes in parallel with the Swift naming.

So from the latest client naming,

@objc(SFAPAPIClient)
public class SfapAPIClient : NSObject {

I would think this

@objc(SFAPAPIChatGenerationsRequestBody)
public class SfapAPIChatGenerationsRequestBody : NSObject {

cc @wmathurin if you have any other thoughts on the format to align on

[wmathurin]

The funny thing is that the A in SFAP stands for API so SFAP API translates to "salesforce api platform api".
That being said, we didn't start that, the oauth scope is also called "sfap_api".

Should we just call them SfapClient / SfapChat etc ??

[bbirman]

👍 for Swift. For Objective-C we'd normally add the SF or SFSDK prefix which is also funny for this one because if we do SF like SFRest it's SFSfapClient? or Eric I think you had a condensed version before like SFApClient? No preference from me

[JohnsonEricAtSalesforce]

Like @wmathurin said, it's almost like saying "I'll have a chai tea" ☕️ which, of course, translates to Tea-Tea 🤣

So, maybe thinking like someone who's less used to the SF prefix that was used by everything in the legacy Objc codebase: If I were looking for the sfap_api related code in either Swift or Objc the SFAPAPI prefixes seem really intuitive to me for both languages. They're also really consistent with the Android code, even though we uppercased it instead of camel-casing it. It is a bit verbose but that's something the old-school iOS dev in me is also really used to 🤓

I'd lean towards keeping it named similarly to the Android code, being a multi-platform developer as I am.

Outside of this context, I would usually agree we can drop the mandatory SF prefix the Objc code used since that's not really Swifty (is it?).

[JohnsonEricAtSalesforce]

To the end of consistency, I actually found one more camel-cased name I missed earlier (I was so sure I got them all!) 74df154

[wmathurin]

Should it be SfapClient in swift and SFSfapClient in Objective-C ?

[wmathurin]

Maybe SfapError ?

[wmathurin]

Maybe SfapErrorResponseBody ?

[wmathurin]

Almost there!
Sorry to nitpick, but I was thinking SfapClient / SfapError / SfapErrorResponseBody.
SFap* looks like it has the SF prefix we use in Objective-C.