Add first version

Author: Kevin Lefèvre

.gitignore

@@ -1,3 +1,6 @@
+# Tests
+provider_credentials.json
+
 ### OSX ###
 *.DS_Store
 .AppleDouble
@@ -34,6 +37,7 @@ Temporary Items
 
 ## Build generated
 build/
+!dependencies/build
 DerivedData/
 
 ## Various settings
@@ -78,8 +82,7 @@ playground.xcworkspace
 # Carthage
 #
 # Add this line if you want to avoid checking in source code from Carthage dependencies.
-# Carthage/Checkouts
-
+Carthage/Checkouts
 Carthage/Build
 
 # fastlane

.gitmodules

@@ -0,0 +1 @@
+github "antitypical/Result" ~> 2.1.3

Cartfile

@@ -0,0 +1 @@
+github "antitypical/Result" "2.1.3"

Cartfile.resolved

@@ -0,0 +1,51 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of  
+fostering an open and welcoming community, we pledge to respect all people who  
+contribute through reporting issues, posting feature requests, updating  
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free  
+experience for everyone, regardless of level of experience, gender, gender  
+identity and expression, sexual orientation, disability, personal appearance,  
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery  
+* Personal attacks  
+* Trolling or insulting/derogatory comments  
+* Public or private harassment  
+* Publishing other's private information, such as physical or electronic  
+  addresses, without explicit permission  
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or  
+reject comments, commits, code, wiki edits, issues, and other contributions  
+that are not aligned to this Code of Conduct, or to ban temporarily or  
+permanently any contributor for other behaviors that they deem inappropriate,  
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to  
+fairly and consistently applying these principles to every aspect of managing  
+this project. Project maintainers who do not follow or enforce the Code of  
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces  
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be  
+reported by contacting a project maintainer at [kevin.lefevre@snips.ai](mailto:kevin.lefevre@snips.ai) or [jeremie.girault@gmail.com](mailto:jeremie.girault@gmail.com). All  
+complaints will be reviewed and investigated and will result in a response that  
+is deemed necessary and appropriate to the circumstances. Maintainers are  
+obligated to maintain confidentiality with regard to the reporter of an  
+incident.  
+
+
+This Code of Conduct is adapted from the [Moya code of conduct](https://github.com/Moya/contributors/blob/master/Code%20of%20Conduct.md)
+itself adapted from the [Contributor Covenant][homepage],  
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

Documentation/CodeOfConduct.md

@@ -0,0 +1,71 @@
+# Provider quirks
+
+## Rationale
+Email protocol is standardized. However providers implementations often provides extension or variations of these standards.
+
+Postal tries to handle some of the edge cases whenever possible but some specificities have to be handled by the developer according to her choices.
+
+This page is meant to regroup all the documentation we found about these quirks in order to make it easier to find a reference for each case.
+
+## OAuth
+
+For some of the most common providers, [OAuth](https://en.wikipedia.org/wiki/OAuth) is the *mandatory* way to connect:
+
+### GMAIL
+
+#### Using OAuth
+
+Reference: [Google OAuth reference](https://developers.google.com/gmail/xoauth2_protocol)
+
+You can use your favorite library to handle the oauth flow:
+
+- [OAuthSwift](https://github.com/OAuthSwift/OAuthSwift)
+- [SwiftyOAuth](https://github.com/delba/SwiftyOAuth)
+- [And many more...](https://github.com/search?utf8=%E2%9C%93&q=oauth+swift)
+
+**Scope**: The access token will need the following scope to allow an access to imap: `https://mail.google.com/`. 
+
+You will then have to use your oauth access token as the password and your email as the login when connecting.
+
+#### Using password
+
+You can still use your account password if 2fa is not enabled. You will have to allow less secure apps to access your mail first. [The documentation is available here.](https://support.google.com/accounts/answer/6010255?hl=en)
+
+However OAuth is the prefered production solution and you should not ask your users to do this. This solution should only be used for tests or prototyping.
+
+### YAHOO
+
+It should be possible to access yahoo using email and password if 2fa is disabled.
+
+However if 2fa is enabled, you will have to use OAuth. The app is not so easy to create in the yahoo developer interface.
+
+- [A workaround exists here to create an OAuth application that have an email scope despite its absence in yahoo developer interface](http://stackoverflow.com/questions/36058534/how-can-yahoo-mail-be-accessed-by-imap-using-oauth-or-oauth2-authentication)
+- [A more official way to do it](https://developer.yahoo.com/oauth/guide/cck-form.html)
+
+**OAuth Quirk:** at this date (07-02-2016) Yahoo OAuth form for mobile does not have a "switch account" or "disconnect" button. It may be problematic in the cases where you expect the user to connect multiple Yahoo email accounts.
+If you use `SFSafariViewController`, it will put your users in a loop where she can't switch to a new account (because of the cookies left by the previous flow).
+
+**Workaround**: if you want to connect multiple yahoo email accounts, you will have to use a `UIWebView` or `WKWebView` and clear your cookies before opening your oauth flow.
+
+
+## Two factor auth
+
+Two factor authentication can cause of lot of trouble when handling connection.
+Most of the time, it is solved by the web flow displayed by the provider and you won't have to handle this.
+
+### iCloud
+
+In the case of iCloud, the 2fa option exists, but no OAuth flow is provided.
+You will have to ask your user to generate an app-specific passwer [using this link](http://support.apple.com/kb/ht6186)
+
+## Other Provider limitations and variations
+
+### iCloud
+
+There seem to be a hard limit (in bytes) to imap responses. We set a batch size of max. 500 items in the code.
+
+### Common folder names
+
+- Every provider seem to have a different identifier for the spam/junk folder. We discovered a set of default values but this setting can be specified in the imap configuration.
+
+- Every provider seem to have a different identifier for the default/inbox folder. Most of the time the default value of `"INBOX"` will work as a good default when no other folder is found. The best method is to list folders and filter find one having the `.AllMail` attribute, or `.Inbox` if it could not be found.

Documentation/ProviderQuirks.md

@@ -0,0 +1,14 @@
+# Roadmap
+
+A lot has been done, but many more is still missing.
+These are the things we would like to see happen in Postal :
+
+- [ ] more documentation
+- [ ] CocoaPods subspec for RxSwift
+- [ ] CocoaPods try pod demo integration
+- [ ] TravisCI integration
+- [ ] Improve libetpan with more constness and int/long to allow more fluent interactions with swift
+- [ ] SPM integration (with linux integration)
+- [ ] Find ways to add robust tests to the parsing / wrapping
+- [ ] tvOS? watchOS ? 
+- [ ] your own proposition, please [contribute](https://github.com/snipsco/Postal/issues)

Documentation/Roadmap.md

@@ -0,0 +1,21 @@
+# Technical Notes
+
+## How does it work ?
+
+- Postal is a swift wrapper over [libetpan](https://github.com/dinhviethoa/libetpan).
+- Libetpan handles all the low-level imap connection and parsing in a synchronous way. 
+- Postal wraps some features provided by libetpan and exposes them with an high-level asynchronous API.
+- The high level API must be simple and comprehensive swift.
+- Libetpan is provided in the repo as a pre-built static library for a better ease-of-use and easier CocoaPods distrbution
+- Libetpan can be built from source using the shell scripts found in the [dependencies](https://github.com/snipsco/Postal/tree/master/dependencies) folder.
+
+## About mailcore ?
+
+[Mailcore2](https://github.com/MailCore/mailcore2) is a library wrapping libetpan providing a great set of features when interacting with mails.
+
+The main drawback which made us start a fresh library is that Mailcore is an objective-c wrapper over a C++ wrapper over libetpan.
+These layers of complexity makes the library quite awkward to use in cunjunction with swift.
+
+Swift provides a native way to interop with C and libetpan is fully portable. We hope that Postal may be ported to provide its feature set in a fully portable (server swift?) way.
+
+[dependencies]: dependencies/

Documentation/TechnicalNotes.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Snips
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.