Add Brave web search support (#103)

Author: lzell

README.md

@@ -19,6 +19,7 @@ included:
 - OpenRouter
 - DeepSeek
 - Fireworks AI
+- Brave
 
 Your initialization code determines whether requests go straight to the provider or are
 protected through the [AIProxy](https://www.aiproxy.pro) backend.
@@ -100,6 +101,7 @@ offer full demo apps to jump-start your development. Please see the [AIProxyBoot
 * [OpenRouter](#openrouter)
 * [DeepSeek](#deepseek)
 * [Fireworks AI](#fireworks-ai)
+* [Brave](#brave)
 * [Advanced Settings](#advanced-settings)
 
 
@@ -3825,6 +3827,8 @@ not on the messages's `reasoningContent` property. Instead, the reasoning conten
 `message.content` enclosed in `<think></think>` tags:
 
 ```swift
+    import AIProxy
+
     /* Uncomment for BYOK use cases */
     // let fireworksAIService = AIProxy.fireworksAIDirectService(
     //     unprotectedAPIKey: "your-fireworks-key"
@@ -3874,6 +3878,48 @@ not on the messages's `reasoningContent` property. Instead, the reasoning conten
 
 ***
 
+## Brave
+
+When you create a service in the AIProxy dashboard, use `https://api.search.brave.com` as the
+proxy base URL.
+
+```swift
+    import AIProxy
+
+    /* Uncomment for BYOK use cases */
+    // let braveService = AIProxy.braveDirectService(
+    //     unprotectedAPIKey: "your-brave-key"
+    // )
+
+    /* Uncomment for all other production use cases */
+    // let braveService = AIProxy.braveService(
+    //     partialKey: "partial-key-from-your-developer-dashboard",
+    //     serviceURL: "service-url-from-your-developer-dashboard"
+    // )
+
+    do {
+        let searchResult = try await braveService.webSearchRequest(query: "How does concurrency work in Swift 6")
+        let resultCount = searchResult.web?.results?.count ?? 0
+        let urls = searchResult.web?.results?.compactMap { $0.url }
+        print(
+            """
+            Brave responded with \(resultCount) search results.
+            The search returned these urls: \(urls ?? [])
+            """
+        )
+    } catch AIProxyError.unsuccessfulRequest(let statusCode, let responseBody) {
+        print("Receivedt non-200 status code: \(statusCode) with response body: \(responseBody)")
+    } catch {
+        // You may want to catch additional Foundation errors and pop the appropriate UI
+        // to the user. See "How to catch Foundation errors for specific conditions" here:
+        // https://www.aiproxy.com/docs/integration-options.html
+        print("Could not make brave search: \(error.localizedDescription)")
+    }
+```
+
+***
+
+
 ## OpenMeteo
 
 ### How to fetch the weather with OpenMeteo

Sources/AIProxy/AIProxy.swift

@@ -13,7 +13,7 @@ let aiproxyLogger = Logger(
 public struct AIProxy {
 
     /// The current sdk version
-    public static let sdkVersion = "0.68.0"
+    public static let sdkVersion = "0.69.0"
 
     /// - Parameters:
     ///   - partialKey: Your partial key is displayed in the AIProxy dashboard when you submit your provider's key.
@@ -783,6 +783,50 @@ public struct AIProxy {
         )
     }
 
+    /// AIProxy's Brave service
+    ///
+    /// - Parameters:
+    ///   - partialKey: Your partial key is displayed in the AIProxy dashboard when you submit your Brave key.
+    ///     AIProxy takes your Brave key, encrypts it, and stores part of the result on our servers. The part that you include
+    ///     here is the other part. Both pieces are needed to decrypt your key and fulfill the request to Brave.
+    ///
+    ///   - serviceURL: The service URL is displayed in the AIProxy dashboard when you submit your Brave key.
+    ///
+    ///   - clientID: An optional clientID to attribute requests to specific users or devices. It is OK to leave this blank for
+    ///     most applications. You would set this if you already have an analytics system, and you'd like to annotate AIProxy
+    ///     requests with IDs that are known to other parts of your system.
+    ///
+    ///     If you do not supply your own clientID, the internals of this lib will generate UUIDs for you. The default UUIDs are
+    ///     persistent on macOS and can be accurately used to attribute all requests to the same device. The default UUIDs
+    ///     on iOS are pesistent until the end user chooses to rotate their vendor identification number.
+    ///
+    /// - Returns: An instance of BraveService configured and ready to make requests
+    public static func braveService(
+        partialKey: String,
+        serviceURL: String,
+        clientID: String? = nil
+    ) -> BraveService {
+        return BraveProxiedService(
+            partialKey: partialKey,
+            serviceURL: serviceURL,
+            clientID: clientID
+        )
+    }
+
+    /// Service that makes request directly to Brave. No protections are built-in for this service.
+    /// Please only use this for BYOK use cases.
+    ///
+    /// - Parameters:
+    ///   - unprotectedAPIKey: Your Brave API key
+    /// - Returns: An instance of  Brave configured and ready to make requests
+    public static func braveDirectService(
+        unprotectedAPIKey: String
+    ) -> BraveService {
+        return BraveDirectService(
+            unprotectedAPIKey: unprotectedAPIKey
+        )
+    }
+
 #if canImport(AppKit) && !targetEnvironment(macCatalyst)
     public static func encodeImageAsJpeg(
         image: NSImage,

Sources/AIProxy/AIProxyURLRequest.swift

@@ -22,6 +22,11 @@ struct AIProxyURLRequest {
     ) async throws -> URLRequest {
         let deviceCheckToken = await AIProxyDeviceCheck.getToken()
 
+        var proxyPath = proxyPath
+        if !proxyPath.starts(with: "/") {
+            proxyPath = "/\(proxyPath)"
+        }
+
         guard var urlComponents = URLComponents(string: serviceURL),
               let proxyPathComponents = URLComponents(string: proxyPath) else {
             throw AIProxyError.assertion(
@@ -85,6 +90,11 @@ struct AIProxyURLRequest {
         contentType: String? = nil,
         additionalHeaders: [String: String] = [:]
     ) throws -> URLRequest {
+        var path = path
+        if !path.starts(with: "/") {
+            path = "/\(path)"
+        }
+
         guard var urlComponents = URLComponents(string: baseURL),
               let pathComponents = URLComponents(string: path) else {
             throw AIProxyError.assertion(

Sources/AIProxy/AnonymousAccount/AIProxyStorage.swift

@@ -57,7 +57,7 @@ final class AIProxyStorage {
             timestamp: Date().timeIntervalSince1970
         )]
         let data: Data = try accountChain.serialize()
-        let createStatus = try await keychain.create(data: data, scope: .local(keychainAccount: kAIProxyLocalAccount))
+        let createStatus = await keychain.create(data: data, scope: .local(keychainAccount: kAIProxyLocalAccount))
         if createStatus != noErr {
             throw AIProxyError.assertion("Could not write a local account to keychain")
         }
@@ -80,7 +80,7 @@ final class AIProxyStorage {
             throw AIProxyError.assertion("Keychain is not available")
         }
         let data: Data = try account.serialize()
-        return try await keychain.create(data: data, scope: .remote(keychainAccount: kAIProxyRemoteAccount))
+        return await keychain.create(data: data, scope: .remote(keychainAccount: kAIProxyRemoteAccount))
     }
 
     static func clear() async throws {

Sources/AIProxy/AnonymousAccount/AnonymousAccountStorage.swift

@@ -54,7 +54,7 @@ final class AnonymousAccountStorage {
         if _localAccountChain == nil {
             _localAccountChain = try await AIProxyStorage.writeNewLocalAccountChain()
         }
-        guard var _localAccountChain = _localAccountChain,
+        guard let _localAccountChain = _localAccountChain,
               var localAccount = _localAccountChain.last else {
             throw AIProxyError.assertion("Broken invariant. localAccount must be populated with at least one element.")
         }
@@ -147,7 +147,7 @@ final class AnonymousAccountStorage {
             return
         }
 
-        guard var resolvedAccount = self.resolvedAccount else {
+        guard let resolvedAccount = self.resolvedAccount else {
             return
         }
 

Sources/AIProxy/Brave/BraveDirectService.swift

@@ -0,0 +1,48 @@
+//
+//  BraveDirectService.swift
+//  AIProxy
+//
+//  Created by Lou Zell on 2/7/25.
+//
+
+import Foundation
+
+open class BraveDirectService: BraveService, DirectService {
+    private let unprotectedAPIKey: String
+
+    /// This initializer is not public on purpose.
+    /// Customers are expected to use the factory `AIProxy.braveDirectService` defined in AIProxy.swift
+    internal init(unprotectedAPIKey: String) {
+        self.unprotectedAPIKey = unprotectedAPIKey
+    }
+
+    /// Makes a web search through Brave. See this reference:
+    /// https://api-dashboard.search.brave.com/app/documentation/web-search/get-started
+    ///
+    /// - Parameters:
+    ///   - query: The query to send to Brave
+    ///   - secondsToWait: Seconds to wait before raising `URLError.timedOut`
+    /// - Returns: The search result. There are many properties on this result, so take some time with
+    ///            BraveWebSearchResponseBody to understand how to get the information you want out of it.
+    public func webSearchRequest(
+        query: String,
+        secondsToWait: Int
+    ) async throws -> BraveWebSearchResponseBody {
+        guard let encodedQuery = query.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) else {
+            throw AIProxyError.assertion("Could not create an encoded version of query params for brave search")
+        }
+        var request = try AIProxyURLRequest.createDirect(
+            baseURL: "https://api.search.brave.com",
+            path: "/res/v1/web/search?q=" + encodedQuery,
+            body: nil,
+            verb: .get,
+            contentType: "application/json",
+            additionalHeaders: [
+                "X-Subscription-Token": self.unprotectedAPIKey
+            ]
+        )
+        request.timeoutInterval = TimeInterval(secondsToWait)
+        return try await self.makeRequestAndDeserializeResponse(request)
+    }
+}
+

Sources/AIProxy/Brave/BraveProxiedService.swift

@@ -0,0 +1,55 @@
+//
+//  BraveProxiedService.swift
+//  AIProxy
+//
+//  Created by Lou Zell on 2/7/25.
+//
+
+import Foundation
+
+open class BraveProxiedService: BraveService, ProxiedService {
+
+    private let partialKey: String
+    private let serviceURL: String
+    private let clientID: String?
+
+    /// This initializer is not public on purpose.
+    /// Customers are expected to use the factory `AIProxy.braveService` defined in AIProxy.swift
+    internal init(
+        partialKey: String,
+        serviceURL: String,
+        clientID: String?
+    ) {
+        self.partialKey = partialKey
+        self.serviceURL = serviceURL
+        self.clientID = clientID
+    }
+
+    /// Makes a web search through Brave. See this reference:
+    /// https://api-dashboard.search.brave.com/app/documentation/web-search/get-started
+    ///
+    /// - Parameters:
+    ///   - query: The query to send to Brave
+    ///   - secondsToWait: Seconds to wait before raising `URLError.timedOut`
+    /// - Returns: The search result. There are many properties on this result, so take some time with
+    ///            BraveWebSearchResponseBody to understand how to get the information you want out of it.
+    public func webSearchRequest(
+        query: String,
+        secondsToWait: Int
+    ) async throws -> BraveWebSearchResponseBody {
+        guard let encodedQuery = query.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) else {
+            throw AIProxyError.assertion("Could not create an encoded version of query params for brave search")
+        }
+        var request = try await AIProxyURLRequest.create(
+            partialKey: self.partialKey,
+            serviceURL: self.serviceURL,
+            clientID: self.clientID,
+            proxyPath: "/res/v1/web/search?q=" + encodedQuery,
+            body: nil,
+            verb: .get,
+            contentType: "application/json"
+        )
+        request.timeoutInterval = TimeInterval(secondsToWait)
+        return try await self.makeRequestAndDeserializeResponse(request)
+    }
+}

Sources/AIProxy/Brave/BraveService.swift

@@ -0,0 +1,30 @@
+//
+//  BraveService.swift
+//  AIProxy
+//
+//  Created by Lou Zell on 2/7/25.
+//
+
+import Foundation
+
+public protocol BraveService {
+
+    /// Makes a web search through Brave. See this reference:
+    /// https://api-dashboard.search.brave.com/app/documentation/web-search/get-started
+    ///
+    /// - Parameters:
+    ///   - query: The query to send to Brave
+    ///   - secondsToWait: Seconds to wait before raising `URLError.timedOut`
+    /// - Returns: The search result. There are many properties on this result, so take some time with
+    ///            BraveWebSearchResponseBody to understand how to get the information you want out of it.
+    func webSearchRequest(
+        query: String,
+        secondsToWait: Int
+    ) async throws -> BraveWebSearchResponseBody
+}
+
+extension BraveService {
+    public func webSearchRequest(query: String) async throws -> BraveWebSearchResponseBody {
+        return try await self.webSearchRequest(query: query, secondsToWait: 60)
+    }
+}