|
| 1 | +# @conjoon/extjs-app-webmail |
| 2 | +This Sencha ExtJS NPM package is built with the [coon.js-library](https://github.com/coon.js) and provides a webmail client |
| 3 | +implementation for the [conjoon](https://github.com/conjoon/conjoon) application. |
| 4 | + |
| 5 | +## Installation |
| 6 | +``` |
| 7 | +npm install --save-dev @conjoon/extjs-app-webmail |
| 8 | +``` |
| 9 | +If you want to develop with this package, run the `build:dev`-script afterwards: |
| 10 | +```bash |
| 11 | +npm run build:dev |
| 12 | +``` |
| 13 | +Testing environment will then be available via |
| 14 | + |
| 15 | +```bash |
| 16 | +npm test |
| 17 | +``` |
| 18 | + |
| 19 | +## Usage |
| 20 | +When using this package without a backend implementation, make sure your app uses the [extjs-dev-webmailsim](https://github.com/conjoon/extjs-dev-webmailsim) package of the [conjoon](https://github.com/conjoon) project. |
| 21 | + |
| 22 | +### Available API Implementations |
| 23 | +A simplistic RESTful PHP backend that can be used with single sign-ons to existing IMAP Servers can be found at [php-cn_imapuser](https://github.com/conjoon/php-cn_imapuser). |
| 24 | + |
| 25 | +### Required API |
| 26 | +The following API calls are made from `extjs-app-webmail` |
| 27 | + |
| 28 | +* `cn_mail/MailAccounts` | **GET** |
| 29 | + * **Parameters:** - |
| 30 | + * Returns a list of all available Email-Accounts according to the model found in `conjoon.cn_mail.model.mail.account.MailAccount`. Failed attempts to retrieve this list should return appropriate http Status-Code. |
| 31 | + * Success Status / Response: Status 200 `{success : true, data : [{...}, {...}, ...] ` |
| 32 | + * Failure Status / Response: Status * `{success : false}` |
| 33 | + |
| 34 | +* `cn_mail/MailAccounts/{mailAccountId}/MailFolders` | **GET** |
| 35 | +* **Parameters:** |
| 36 | + * `{mailAccountId}` (required): The id of the MailAccount for which the folders should be queried. |
| 37 | +* Returns a list of all folders for the MailAccount with the specified `mailAccountId`, according to the model found in `conjoon.cn_mail.model.mail.folder.MailFolder`; child-folders should be available in the `data`-property of each folder. Failed attempts to retrieve this list should return appropriate http Status-Code. |
| 38 | +* Success Status / Response: Status 200 `{success : true, data : []}` |
| 39 | +* Failure Status / Response: Status * `{success : false}` |
| 40 | + |
| 41 | +* `cn_mail/MailAccounts/{mailAccountId}/MailFolders/{mailFolderId}/MessageItems` | **POST** |
| 42 | + * **Parameters:** |
| 43 | + * `{mailAccountId}` (required): The id of the MailAccount for which the Message should be queried; |
| 44 | + * `{mailFolderId}` (required): The id of the folder for which the Message should be returned; |
| 45 | + * `{messageItemId}` (required): The id of the Message to return; |
| 46 | + * `{target}` (required): if `{target=MessageBody}` is set, only the the MessageBody should be created and returned; if `{target=MessageItem}` is set, only MessageItem-informations should be created and returned; |
| 47 | + * Returns the created MessageBody or MessageItem for the specified parameters. |
| 48 | + * Success Status / Response: Status 200 `{success : true, data : {}}` |
| 49 | + * Failure Status / Response: Status * `{success : false}`; if the parameter `{target}` is missing, a *400 - Bad Request* should be returned |
| 50 | + |
| 51 | +* `cn_mail/MailAccounts/{mailAccountId}/MailFolders/{mailFolderId}/MessageItems?{start}&limit&{sort}` | **GET** |
| 52 | + * **Parameters:** |
| 53 | + * `{mailAccountId}` (required): The id of the MailAccount for which the folders should be queried; |
| 54 | + * `{mailFolderId}` (required): The id of the folder for which the messages should be returned; |
| 55 | + * `{start}` (required): The first index of the list to return; |
| 56 | + * `{limit}` (required): The number of items to return; |
| 57 | + * `{sort}` an array with sorting informations the client requests, e.g.: `sort=[{property : date, direction : DESC}]` |
| 58 | + * Returns a list of all MessageItems for the MailAccount with the specified `mailAccountId` found in the mailbox with the id `mailFolderId`, according to the model found in `conjoon.cn_mail.model.mail.message.MessageItem`; Failed attempts to retrieve this list should return appropriate http Status-Code. This response returns a list of MessageItems in the boundaries of `start` and `start + limit`; meta-information in the response need to contain the current number of unread messages in the queried mailbox along with the mailbox's identifier (`mailFolderId`) and the associated account (`mailAccountId`) itself. |
| 59 | + * Success Status / Response: Status 200 `{success : true, total : (int), meta : {unreadCount : (int), mailFolderId : (string), mailAccountId : (string)}, data : []}` |
| 60 | + * Failure Status / Response: Status * `{success : false}` |
| 61 | + |
| 62 | +* `cn_mail/MailAccounts/{mailAccountId}/MailFolders/{mailFolderId}/MessageItems/{messageItemId}` | **GET** |
| 63 | + * **Parameters:** |
| 64 | + * `{mailAccountId}` (required): The id of the MailAccount for which the Message should be queried; |
| 65 | + * `{mailFolderId}` (required): The id of the folder for which the Message should be returned; |
| 66 | + * `{messageItemId}` (required): The id of the Message to return; |
| 67 | + * `{target}` (required): if `{target=MessageBody}` is set, only the the MessageBody should be returned; if `{target=MessageItem}` is set, only MessageItem-informations should be returned; |
| 68 | + * Returns the MessageItem or MessageBody for the specified parameters. |
| 69 | + * Success Status / Response: Status 200 `{success : true, data : {}}` |
| 70 | + * Failure Status / Response: Status * `{success : false}`; if the parameter `{target}` is missing, a *400 - Bad Request* should be returned |
| 71 | + |
| 72 | +* `cn_mail/MailAccounts/{mailAccountId}/MailFolders/{mailFolderId}/MessageItems/{messageItemId}` | **PUT** |
| 73 | + * **Parameters:** |
| 74 | + * `{mailAccountId}` (required): The id of the MailAccount for which the Message should be queried; |
| 75 | + * `{mailFolderId}` (required): The id of the folder for which the Message should be returned; |
| 76 | + * `{messageItemId}` (required): The id of the Message to return; |
| 77 | + * `{target}` (required): `{target=MessageItem}` |
| 78 | + * `{origin}` (required): `{origin=create}` - Required for MessageDrafts to determine if they were initially created |
| 79 | + * `{action}` (required): `{action=move}` - Required to determine if a move operation is requested by the client |
| 80 | + * The following data can be submitted: |
| 81 | + * `seen (true/false)` sets the \Seen flag for the specified Message (for `{target=MessageItem}`) |
| 82 | + * `flagged (true/false)` sets the \Flagged flag for the specified Message (for `{target=MessageItem}`) |
| 83 | + * `draft (true/false)` sets the \Draft flag for the specified Message (for `{target=MessageItem}`) |
| 84 | + * `mailFolderId (String)` requests a move operation for the specified Message (for `{target=MessageItem}` along with `{action=move}`) |
| 85 | + * For `{target=MessageDraft}`, data described in the `conjoon.cn_mail.model.mail.message.MessageDraft` can be submitted |
| 86 | + * Success Status / Response: |
| 87 | + * Status 200 `{success : true, data :{id : (string), mailFolderId : (string), mailAccountId : (string), seen : (bool), flagged : (bool)}}` If the operation was successfull, the data must contain the id, the mailFolderId and the mailAccountId representing the compound key of the message, along with the properties `seen` and/or `flagged` and their newly set value. If a new mailFolderId was submitted with the request, the response must contain a json-encoded MessageItem. See below. |
| 88 | + * Status 200 `{success : true, data :{[json encoded MessageItem along with preview-text]}}` If the operation was successful, the data must contain a json encoded MessageItem along with the preview-text. |
| 89 | + * Failure Status / Response: Status * `{success : false}`; if the parameter `{target}` is not valid, or the request payload is invalid, a *400 - Bad Request* should be returned. If a move operation for a MessageItem was requested, and the submitted `mailFolderId` is the same as the current for the target MessageItem, a *400 - Bad Request* should be returned. |
| 90 | + |
| 91 | +##Dev |
| 92 | +### Naming |
| 93 | +The following naming conventions apply: |
| 94 | + |
| 95 | +#### Namespace |
| 96 | +`conjoon.cn_mail.*` |
| 97 | +#### Package name |
| 98 | +`extjs-app-webmail` |
| 99 | +#### Shorthand to be used with providing aliases |
| 100 | +`cn_mail` |
| 101 | + |
| 102 | +**Example:** |
| 103 | +Class `conjoon.cn_mail.view.mail.MailDesktopViewModel` has the alias `viewmodel.cn_mail-maildesktopviewmodel` |
| 104 | + |
| 105 | +## Tests |
| 106 | +Tests are written with [Siesta](https://bryntum.com/siesta) |
0 commit comments