Skip to content

Commit c8188ee

Browse files
devwaseemdevwaseem
authored
Add sample codes in documentation for service classes (#7)
* Add sample code in documentation for `MTAccountService` and `MTAPIServiceTask` * Add sample code in documentation for `MTDomainService` class * Add sample code in documentation for `MTLiveMessagesService`. Add minimum requirements for `MTLiveMessagesService` in README.md
1 parent b2fb83e commit c8188ee

File tree

6 files changed

+223
-9
lines changed

6 files changed

+223
-9
lines changed

‎README.md

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -141,11 +141,11 @@ To get details of a specific domain:
141141
```swift
142142
import MailTMSwift
143143

144-
let id = ""
144+
let id = // domain ID
145145
domainService.getDomain(id: id) { (result: Result<MTDomain, MTError>) in
146146
switch result {
147-
case .success(let domains):
148-
print("Available domains: \(domains)")
147+
case .success(let domain):
148+
print("Domain: \(domain)")
149149
case .failure(let error):
150150
print("Error occurred \(error)")
151151
}
@@ -265,7 +265,13 @@ messageService.deleteMessage(id: id, token: token) { (result: Result<MTEmptyResu
265265

266266
[`MTLiveMailService`](https://mailtmswift.waseem.works/documentation/mailtmswift/mtlivemailservice) uses Apple's Combine framework to listen for live events. Make sure you use the required minimum version of the platform you're using this package.
267267

268-
>
268+
### Requirements
269+
270+
| Platform | Minimum required version |
271+
| iOS | 13.0+ |
272+
| macOS | 10.15+ |
273+
| watchOS | 6.0+ |
274+
| tvOS | 13.0+ |
269275

270276
### Setup
271277

‎Sources/MailTMSwift/APIService.swift

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,16 @@ public protocol MTAPIServiceTaskProtocol {
193193
func cancel()
194194
}
195195

196-
/// Wrapper class for URLSessionDataTask, provided to cancel the ongoing api request
196+
/**
197+
Wrapper class for URLSessionDataTask, provided to cancel the ongoing api request
198+
199+
You can call ``MTAPIServiceTask/cancel()`` method to cancel the ongoing API request.
200+
```swift
201+
let task = messageService.deleteMessage(id: id, token: token) { ... }
202+
// cancel request
203+
task.cancel()
204+
```
205+
*/
197206
public final class MTAPIServiceTask: MTAPIServiceTaskProtocol {
198207
private let sessionTask: URLSessionDataTask
199208

‎Sources/MailTMSwift/Services/MTAccountService.swift

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,20 @@ open class MTAccountService {
2828
/// - auth: ``MTAuth`` struct which holds address and password
2929
/// - completion: when successful, returns a `Result` type with JWT token string and ``MTError`` if some error occurred
3030
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
31+
///
32+
/// Example:
33+
///```swift
34+
///let auth = MTAuth(address: "[email protected]", password: "12345678")
35+
///let accountService = MTAccountService()
36+
///accountService.login(using: auth) { (result: Result<String, MTError>) in
37+
/// switch result {
38+
/// case .success(let token):
39+
/// print("got JWT: \(token)")
40+
/// case .failure(let error):
41+
/// print("Error occurred \(error)")
42+
/// }
43+
///}
44+
///```
3145
@discardableResult
3246
open func login(using auth: MTAuth, completion: @escaping (Result<String, MTError>) -> Void) -> MTAPIServiceTaskProtocol {
3347
apiService.request(method: .post,
@@ -49,6 +63,21 @@ open class MTAccountService {
4963
/// - auth: ``MTAuth`` struct which holds address and password
5064
/// - completion: when successful, returns a `Result` type with ``MTAccount`` and ``MTError`` if some error occurred
5165
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
66+
///
67+
/// Example:
68+
/// ```swift
69+
/// let auth = MTAuth(address: "[email protected]", password: "12345678")
70+
/// let accountService = MTAccountService()
71+
/// accountService.createAccount(using: auth) { (accountResult: Result<MTAccount, MTError>) in
72+
/// switch accountResult {
73+
/// case .success(let account):
74+
/// print("Created an account \(account)")
75+
/// case .failure(let error):
76+
/// print("Error occurred \(error)")
77+
/// }
78+
/// }
79+
/// ```
80+
/// - Note: This method returns account document but not JWT token. You need JWT token to authorize protected endpoints. To fetch JWT token, use ``MTAccountService/login(using:completion:)``
5281
@discardableResult
5382
open func createAccount(using auth: MTAuth, completion: @escaping (Result<MTAccount, MTError>) -> Void) -> MTAPIServiceTaskProtocol {
5483
apiService.request(
@@ -80,6 +109,23 @@ open class MTAccountService {
80109
/// - completion: when successful, returns a `Result` type with ``MTEmptyResult`` and ``MTError`` if some error occurred
81110
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
82111
///
112+
/// Example:
113+
/// ```swift
114+
/// let id = // Account ID
115+
/// let token = // Account JWT token
116+
/// let accountService = MTAccountService()
117+
/// accountService.deleteAccount(id: id, token: token) { (result: Result<MTEmptyResult, MTError>) in
118+
/// if case let .failure(error) = result {
119+
/// print("Error Occurred: \(error)")
120+
/// return
121+
/// }
122+
///
123+
/// // Account deleted
124+
/// doSomethingAfterDelete()
125+
/// }
126+
/// ```
127+
///
128+
///
83129
/// - Note: When deletion is successful, the API returns empty response which indicates successful operation.
84130
@discardableResult
85131
open func deleteAccount(id: String, token: String, completion: @escaping (Result<MTEmptyResult, MTError>) -> Void) -> MTAPIServiceTaskProtocol {

‎Sources/MailTMSwift/Services/MTDomainService.swift

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,19 @@ open class MTDomainService {
2626
/// Get all domains that [Mail.tm](https://mail.tm) offers
2727
/// - Parameter completion: when successful, returns a `Result` type with the list of ``MTDomain`` and ``MTError`` if some error occurred
2828
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
29+
///
30+
/// Example:
31+
/// ```swift
32+
/// let domainService = MTDomainService()
33+
/// domainService.getAllDomains { (result: Result<[MTDomain], MTError>) in
34+
/// switch result {
35+
/// case .success(let domains):
36+
/// print("Available domains: \(domains)")
37+
/// case .failure(let error):
38+
/// print("Error occurred \(error)")
39+
/// }
40+
/// }
41+
/// ```
2942
@discardableResult
3043
open func getAllDomains(completion: @escaping (Result<[MTDomain], MTError>) -> Void) -> MTAPIServiceTaskProtocol {
3144
apiService.get(endpoint: Endpoints.domains, authToken: nil, headers: [:]) { (result: Result<HydraWrapper<[MTDomain]>, MTError>) in
@@ -43,6 +56,20 @@ open class MTDomainService {
4356
/// - id: domain id
4457
/// - completion: when successful, returns a `Result` type with ``MTDomain`` and ``MTError`` if some error occurred
4558
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
59+
///
60+
/// Example:
61+
/// ```swift
62+
/// import MailTMSwift
63+
/// let id = // domain ID
64+
/// domainService.getDomain(id: id) { (result: Result<MTDomain, MTError>) in
65+
/// switch result {
66+
/// case .success(let domain):
67+
/// print("Domain: \(domain)")
68+
/// case .failure(let error):
69+
/// print("Error occurred \(error)")
70+
/// }
71+
/// }
72+
/// ```
4673
@discardableResult
4774
open func getDomain(id: String, completion: @escaping (Result<MTDomain, MTError>) -> Void) -> MTAPIServiceTaskProtocol {
4875
apiService.get(endpoint: Endpoints.domainFromId(id), authToken: nil, headers: [:], completion: completion)

‎Sources/MailTMSwift/Services/MTLiveMailService.swift

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,23 @@ import Combine
1010
import LDSwiftEventSource
1111

1212
/// A service class to listen for live create/update events for Accounts and Messages.
13+
///
14+
/// Example:
15+
/// ```swift
16+
/// import MailTMSwift
17+
/// import Combine
18+
///
19+
/// let subscriptions = Set<AnyCancellable>()
20+
/// let token = // Account JWT token
21+
/// let id = // Account id
22+
/// let liveMailService = MTLiveMailService(token: token, accountId: id)
23+
/// ```
24+
///
1325
/// - Note: Internally it uses SSE events to listen for live events
1426
@available(macOS 10.15, *)
1527
@available(iOS 13.0, *)
1628
@available(watchOS 6.0, *)
1729
@available(tvOS 13.0, *)
18-
@available(tvOS 13.0, *)
1930
open class MTLiveMailService {
2031

2132
/// State of connection
@@ -28,6 +39,17 @@ open class MTLiveMailService {
2839
private var eventSource: EventSource?
2940

3041
/// A publisher that emits ``MTLiveMailService/State`` when the status of connection changes
42+
///
43+
/// Example:
44+
/// ```swift
45+
/// liveMailService.statePublisher.sink { state in
46+
/// if state == .opened {
47+
/// print("Connected to server")
48+
/// } else {
49+
/// print("Disconnected to server")
50+
/// }
51+
/// }.store(in: &subscriptions)
52+
/// ```
3153
public var statePublisher: AnyPublisher<MTLiveMailService.State, Never> {
3254
$state
3355
.receive(on: DispatchQueue.main, options: .init(qos: .utility))
@@ -37,13 +59,29 @@ open class MTLiveMailService {
3759
@Published private var state = State.closed
3860

3961
/// A publisher that emits ``MTMessage`` when the message is received/deleted/updated
62+
///
63+
/// Example:
64+
/// ```swift
65+
/// liveMailService.messagePublisher.sink { message in
66+
/// print("Received message event: \(message)")
67+
/// }
68+
/// .store(in: &subscriptions)
69+
/// ```
4070
public var messagePublisher: AnyPublisher<MTMessage, Never> {
4171
_messagePublisher
4272
.receive(on: DispatchQueue.main, options: .init(qos: .utility))
4373
.eraseToAnyPublisher()
4474
}
4575

4676
/// A publisher that emits ``MTAccount`` when account is updated.
77+
///
78+
/// Example:
79+
/// ```swift
80+
/// liveMailService.accountPublisher.sink { account in
81+
/// print("Received account event: \(account)")
82+
/// }
83+
/// .store(in: &subscriptions)
84+
/// ```
4785
public var accountPublisher: AnyPublisher<MTAccount, Never> {
4886
_accountPublisher
4987
.receive(on: DispatchQueue.main, options: .init(qos: .utility))
@@ -59,7 +97,7 @@ open class MTLiveMailService {
5997
private let accountId: String
6098

6199
/// Retry the listener automatically when the connection goes off
62-
/// - Note: Default is true
100+
/// - Note: Default is false
63101
var autoRetry = false
64102

65103
/// Create a new instance

‎Sources/MailTMSwift/Services/MTMessagesService.swift

Lines changed: 90 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,23 @@ open class MTMessageService {
2929
/// - token: account JWT token
3030
/// - completion: when successful, returns a completion handler `Result` type of array of``MTMessage`` and ``MTError`` if some error occurred
3131
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
32-
/// - Note: Messages received will not be complete. Use the retreived messages to show a list of messages.
33-
/// To retreive the complete message, use ``MTMessageService/getMessage(id:token:)``.
32+
///
33+
/// Example:
34+
/// ```swift
35+
/// let messageService = MTMessageService()
36+
/// let token = // Account JWT token
37+
/// messageService.getAllMessages(token: token) { (result: Result<[MTMessage], MTError>) in
38+
/// switch result {
39+
/// case .success(let messages):
40+
/// for message in messages {
41+
/// print("Message: \(message)")
42+
/// }
43+
/// case .failure(let error):
44+
/// print("Error occurred \(error)")
45+
/// }
46+
/// }
47+
/// ```
48+
/// - Note: The messages returned by this method does not contain complete information, because it is intended to list the messages as list. To fetch the complete message with the complete information, use ``MTMessageService/getMessage(id:token:)``
3449
@discardableResult
3550
public func getAllMessages(page: Int = 1, token: String,
3651
completion: @escaping (Result<[MTMessage], MTError>) -> Void) -> MTAPIServiceTaskProtocol {
@@ -61,6 +76,22 @@ open class MTMessageService {
6176
/// - token: account JWT token
6277
/// - completion: when successful, returns a completion handler `Result` type of ``MTEmptyResult`` and ``MTError`` if some error occurred
6378
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
79+
///
80+
/// Example:
81+
/// ```swift
82+
/// let messageService = MTMessageService()
83+
/// let id = // Message ID
84+
/// let token = // Account JWT token
85+
/// messageService.deleteMessage(id: id, token: token) { (result: Result<MTEmptyResult, MTError>) in
86+
/// if case let .failure(error) = result {
87+
/// print("Error Occurred: \(error)")
88+
/// return
89+
/// }
90+
///
91+
/// // Message deleted
92+
/// doSomethingAfterDelete()
93+
/// }
94+
/// ```
6495
/// - Note: When a message is successfully deleted, the server sends a empty response.
6596
@discardableResult
6697
public func deleteMessage(id: String, token: String, completion: @escaping (Result<MTEmptyResult, MTError>) -> Void) -> MTAPIServiceTaskProtocol {
@@ -78,6 +109,21 @@ open class MTMessageService {
78109
/// - token: account JWT token
79110
/// - completion: when successful, returns a completion handler `Result` type of ``MTMessage`` and ``MTError`` if some error occurred
80111
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
112+
///
113+
/// Example:
114+
/// ```swift
115+
/// let messageService = MTMessageService()
116+
/// let id = // Message ID
117+
/// let token = // Account JWT token
118+
/// messageService.getMessage(id: id, token: token) { (result: Result<MTMessage, MTError>) in
119+
/// switch result {
120+
/// case .success(let message):
121+
/// print("Complete message: \(message)")
122+
/// case .failure(let error):
123+
/// print("Error occurred \(error)")
124+
/// }
125+
/// }
126+
/// ```
81127
@discardableResult
82128
public func getMessage(id: String, token: String, completion: @escaping (Result<MTMessage, MTError>) -> Void) -> MTAPIServiceTaskProtocol {
83129
apiService.get(endpoint: Endpoints.messagesFromId(id), authToken: token, headers: [:], completion: completion)
@@ -90,6 +136,21 @@ open class MTMessageService {
90136
/// - token: account JWT Token
91137
/// - completion: when successful, returns a completion handler `Result` type of ``MTMessage`` and ``MTError`` if some error occurred
92138
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
139+
///
140+
/// Example:
141+
/// ```swift
142+
/// let messageService = MTMessageService()
143+
/// let id = // Message ID
144+
/// let token = // Account JWT token
145+
/// messageService.markMessageAs(id: id, seen: true, token: token) { (result: Result<MTMessage, MTError>) in
146+
/// switch result {
147+
/// case .success(let message):
148+
/// print("Updated message: \(message)")
149+
/// case .failure(let error):
150+
/// print("Error occurred \(error)")
151+
/// }
152+
/// }
153+
/// ```
93154
@discardableResult
94155
public func markMessageAs(id: String,
95156
seen: Bool,
@@ -109,6 +170,22 @@ open class MTMessageService {
109170
/// - token: account JWT token
110171
/// - completion: when successful, returns a completion handler `Result` type of ``MTMessageSource`` and ``MTError`` if some error occurred
111172
/// - Returns: ServiceTask which can be used to cancel on-going http(s) request
173+
///
174+
/// Example:
175+
///
176+
/// ```swift
177+
/// let messageService = MTMessageService()
178+
/// let id = // Message ID
179+
/// let token = // Account JWT token
180+
/// messageService.getSource(id: id, token: token) { (result: Result<MTMessageSource, MTError>) in
181+
/// switch result {
182+
/// case .success(let messageSource):
183+
/// print("Message source: \(messageSource)")
184+
/// case .failure(let error):
185+
/// print("Error occurred \(error)")
186+
/// }
187+
/// }
188+
/// ```
112189
@discardableResult
113190
public func getSource(id: String,
114191
token: String,
@@ -226,6 +303,17 @@ open class MTMessageService {
226303
/// - id: message id
227304
/// - token: account JWT Token
228305
/// - Returns: `URLRequest` configured to retreive message source.
306+
///
307+
/// If the size of message is big and you wish to use a downloadTask from URLSession, you can do so manually by using the URLRequest object returned by:
308+
/// ```swift
309+
/// let messageService = MTMessageService()
310+
/// let id = // Message ID
311+
/// let token = // Account JWT token
312+
/// let urlRequest = messageService.getSourceRequest(id: id, token: token)
313+
/// let task = URLSession.shared.downloadTask(with: request)
314+
/// // handle download task
315+
/// ```
316+
///
229317
/// - Note: This method will return nil, if the message source url is nil.
230318
public func getSourceRequest(id: String, token: String) -> URLRequest? {
231319
guard let url = URL(string: Endpoints.sourcesFromId(id)) else {

0 commit comments

Comments
 (0)