diff --git a/CHANGELOG.md b/CHANGELOG.md index fd2e867..9644726 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Change Log +## Version 10.0.1 (March 29, 2022) +Minor update. +* Added inline code documentation. +* Updated README.md. +* Made `ResponseError` public. + ## Version 10.0.0 (March 28, 2022) Major 'breaking' release. Highlights: * Replaces Swift Combine publishers with Swift Concurrency (async/await) model diff --git a/Sources/SwiftlySalesforce/Connection+API.swift b/Sources/SwiftlySalesforce/Connection+API.swift index 75d2a21..51e2f0a 100644 --- a/Sources/SwiftlySalesforce/Connection+API.swift +++ b/Sources/SwiftlySalesforce/Connection+API.swift @@ -5,13 +5,25 @@ public extension Connection { /// Retrieves information about limits in your org. /// For each limit, this method returns the maximum allocation and the remaining allocation based on usage. /// - /// See: [Limits](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_limits.htm) + /// [Limits](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_limits.htm) + /// + /// - Returns: A dictionary of ``Limit`` instances. /// - /// - Returns: A dictionary of ``Limit`` instances func limits() async throws -> [String: Limit] { return try await request(service: Resource.Limits()) } + /// Performs a query. + /// + /// - [Query](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm) + /// - [SOQL and SOSL Reference](https://developer.salesforce.com/docs/atlas.en-us.232.0.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_sosl_intro.htm) + /// + /// - Parameters: + /// - soql: A SOQL query string. + /// - batchSize: A numeric value that specifies the number of records returned for a query request. + /// + /// - Returns: ``QueryResult`` + /// func query(soql: String, batchSize: Int? = nil) async throws -> QueryResult { return try await request(service: Resource.Query.Run(soql: soql, batchSize: batchSize)) } @@ -28,14 +40,45 @@ public extension Connection { return try await request(service: Resource.Query.MyRecords(type: type, fields: fields, limit: limit, batchSize: batchSize)) } + /// Searches for a string in Salesforce record fields + /// + /// [SOQL and SOSL Reference](https://developer.salesforce.com/docs/atlas.en-us.232.0.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_sosl_intro.htm) + /// + /// - Parameters: + /// - sosl: A SOSL query string. + /// + /// - Returns: + /// - An array of records that match the search criteria. + /// func search(sosl: String) async throws -> [Record] { return try await request(service: Resource.Search(sosl: sosl)) } + /// Inserts a Salesforce record + /// + /// - Parameters: + /// - type: Type of record (e.g. `Account`, `Contact` or `MyCustomObject__c`). + /// - fields: Dictionary of fields names and values to insert. + /// + /// - Returns: Publisher that emits the ID of the successfully-inserted record, or an error. + /// func insert(type: String, fields: [String: T]) async throws -> String { return try await request(service: Resource.SObjects.Create(type: type, fields: fields)) } + /// Retrieves a Salesforce record. + /// + /// [Working with Records](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/using_resources_working_with_records.htm) + /// + /// - Parameters: + /// - type: Type of record (e.g. "Account", "Contact" or "MyCustomObject__c"). + /// - id: Unique ID of the record; 15 or 18 characters. + /// - fields: Fields to retrieve. If nil, then all fields will be retrieved. + /// + /// - Returns: A Salesforce record. + /// + /// - Throws: ``ResponseError`` if the record can't be found or if the request can't be completed. + /// func read(type: String, id: String, fields: [String]? = nil) async throws -> T { return try await request(service: Resource.SObjects.Read(type: type, id: id, fields: fields)) } @@ -44,40 +87,76 @@ public extension Connection { return try await request(service: Resource.SObjects.Read(type: type, id: id, fields: fields)) } + /// Updates a Salesforce record + /// + /// - Parameters: + /// - type: Type of record (e.g. `Account`, `Contact` or `MyCustomObject__c`). + /// - id: Unique ID of the record; 15 or 18 characters. + /// - fields: Dictionary of fields names and values to update. + /// + /// - Returns: Void; no return value. + /// func update(type: String, id: String, fields: [String: T]) async throws -> Void { return try await request(service: Resource.SObjects.Update(type: type, id: id, fields: fields)) } + /// Deletes a Salesforce record + /// + /// - Parameters: + /// - type: Type of record (e.g. `Account`, `Contact` or `MyCustomObject__c`). + /// - id: Unique ID of the record; 15 or 18 characters. + /// + /// - Returns: Void; no return value. + /// func delete(type: String, id: String) async throws -> Void { return try await request(service: Resource.SObjects.Delete(type: type, id: id)) } + /// Retrieves metadata about a Salesforce object. + /// + /// [sObject Describe](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_describe.htm) + /// + /// - Parameters: + /// - type: Type of record (e.g. `Account`, `Contact` or `MyCustomObject__c`). + /// + /// - Returns: An ``ObjectDescription`` instance. + /// func describe(type: String) async throws -> ObjectDescription { return try await request(service: Resource.SObjects.Describe(type: type)) } + /// Describes all accessible objects in the user's Salesforce org. + /// + /// [sObject Describe](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_describe.htm) + /// + /// - Returns: An array of ``ObjectDescription`` instances. + /// func describeGlobal() async throws -> [ObjectDescription] { return try await request(service: Resource.SObjects.DescribeGlobal()) } /// Gets information about the current user + /// /// - Returns: An ``Identity`` instance. + /// func identity() async throws -> Identity { return try await request(service: IdentityService()) } - /// Represents a call to an Apex class exposed as a REST service. + /// Calls an Apex class exposed as a REST service. /// - /// See [Introduction to Apex REST](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_rest_intro.htm) in the Salesforce documentation. + /// [Introduction to Apex REST](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_rest_intro.htm) /// /// - Parameters: - /// - method: Optional, HTTP method to use; if `nil` then GET will be used in the request. - /// - path: Path to the Apex REST service, as defined in the `urlMapping` of the `@RestResource` annotation on the target class. - /// - queryItems: Optional query items to include in the request. - /// - headers: Optional `HTTP` headers to include in the request. - /// - body: Request body for a `POST` , `PATCH` or `PUT` request. - /// - timeoutInterval: request timeout interval, in seconds. + /// - method: Optional, HTTP method to use; if `nil` then GET will be used in the request. + /// - path: Path to the Apex REST service, as defined in the `urlMapping` of the `@RestResource` annotation on the target class. + /// - queryItems: Optional query items to include in the request. + /// - headers: Optional `HTTP` headers to include in the request. + /// - body: Request body for a `POST` , `PATCH` or `PUT` request. + /// - timeoutInterval: request timeout interval, in seconds. + /// /// - Returns: The `Decodable` return value from the Apex class. + /// func apex( method: String? = nil, path: String, diff --git a/Sources/SwiftlySalesforce/Errors/ResponseError.swift b/Sources/SwiftlySalesforce/Errors/ResponseError.swift index 265d999..7cc9020 100644 --- a/Sources/SwiftlySalesforce/Errors/ResponseError.swift +++ b/Sources/SwiftlySalesforce/Errors/ResponseError.swift @@ -1,11 +1,11 @@ import Foundation -struct ResponseError: Error { +public struct ResponseError: Error { - var code: String? = nil - var message: String? = nil - var fields: [String]? = nil - let metadata: HTTPURLResponse + public var code: String? = nil + public var message: String? = nil + public var fields: [String]? = nil + public let metadata: HTTPURLResponse private let na = "N/A" // 'Not Applicable' or 'Not Available' } @@ -19,7 +19,7 @@ extension ResponseError: LocalizedError { extension ResponseError: CustomDebugStringConvertible { - var debugDescription: String { + public var debugDescription: String { let na = "N/A" // 'Not Applicable' or 'Not Available' let fieldStr = fields?.joined(separator: ", ") ?? na return "Salesforce response error. Code: \(code ?? na). Message: \(message ?? na). Fields: \(fieldStr). HTTP Status Code: \(metadata.statusCode))"