@unireq/imap 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# @unireq/imap
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@unireq/imap)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
|
|
6
|
+
IMAP transport with a pluggable connector architecture. Ships with a default connector powered by `imapflow`, but you can bring your own implementation (BYOC).
|
|
7
|
+
|
|
8
|
+
## Installation
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
pnpm add @unireq/imap
|
|
12
|
+
|
|
13
|
+
# For the default connector (optional peer dependency)
|
|
14
|
+
pnpm add imapflow
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Quick Start
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import { client } from '@unireq/core';
|
|
21
|
+
import { imap, imapOperation } from '@unireq/imap';
|
|
22
|
+
|
|
23
|
+
const { transport } = imap('imap://user:pass@imap.gmail.com');
|
|
24
|
+
const mail = client(transport);
|
|
25
|
+
|
|
26
|
+
// Fetch messages from INBOX
|
|
27
|
+
const messages = await mail.get('/', imapOperation('fetch', { mailbox: 'INBOX' }));
|
|
28
|
+
|
|
29
|
+
// Search for unread messages
|
|
30
|
+
const ids = await mail.get('/', imapOperation('search', {
|
|
31
|
+
mailbox: 'INBOX',
|
|
32
|
+
criteria: { seen: false },
|
|
33
|
+
}));
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Features
|
|
37
|
+
|
|
38
|
+
| Category | Symbols | Purpose |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| Transport | `imap(uri?, connector?)` | IMAP/IMAPS transport factory |
|
|
41
|
+
| Default connector | `ImapFlowConnector` | Implementation using `imapflow` |
|
|
42
|
+
| Policy | `imapOperation(op, options?)` | Inject operation into context |
|
|
43
|
+
| Auth | `xoauth2({ tokenSupplier })` | OAuth2 authentication policy |
|
|
44
|
+
| Types | `IMAPMessage`, `SearchCriteria` | Message and search structures |
|
|
45
|
+
|
|
46
|
+
## Supported Operations
|
|
47
|
+
|
|
48
|
+
| Operation | Policy | Description |
|
|
49
|
+
| --- | --- | --- |
|
|
50
|
+
| `fetch` | `imapOperation('fetch', { mailbox })` | Fetch messages |
|
|
51
|
+
| `search` | `imapOperation('search', { mailbox, criteria })` | Search messages |
|
|
52
|
+
| `append` | `imapOperation('append', { mailbox? })` | Append message |
|
|
53
|
+
| `move` | `imapOperation('move', { mailbox, destination })` | Move messages |
|
|
54
|
+
| `addFlags` | `imapOperation('addFlags', { mailbox, flags })` | Add flags |
|
|
55
|
+
| `removeFlags` | `imapOperation('removeFlags', { mailbox, flags })` | Remove flags |
|
|
56
|
+
| `expunge` | `imapOperation('expunge', { mailbox })` | Expunge deleted |
|
|
57
|
+
|
|
58
|
+
## Search Criteria
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
const criteria = {
|
|
62
|
+
seen: false,
|
|
63
|
+
from: 'boss@work.com',
|
|
64
|
+
since: new Date('2025-01-01'),
|
|
65
|
+
or: [{ from: 'alice@example.com' }, { from: 'bob@example.com' }],
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
const uids = await mail.get('/', imapOperation('search', {
|
|
69
|
+
mailbox: 'INBOX',
|
|
70
|
+
criteria,
|
|
71
|
+
}));
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## XOAUTH2 Integration
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
import { imap, xoauth2 } from '@unireq/imap';
|
|
78
|
+
import { client, compose } from '@unireq/core';
|
|
79
|
+
|
|
80
|
+
const { transport } = imap('imap://user@gmail.com@imap.gmail.com');
|
|
81
|
+
|
|
82
|
+
const gmail = client(
|
|
83
|
+
compose(transport, xoauth2({ tokenSupplier: () => oauthClient.getAccessToken() })),
|
|
84
|
+
);
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Bring Your Own Connector
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
import type { IMAPConnector, IMAPSession } from '@unireq/imap';
|
|
91
|
+
|
|
92
|
+
class MyImapConnector implements IMAPConnector {
|
|
93
|
+
readonly capabilities = { imap: true, xoauth2: true, idle: true, append: true, search: true, move: true, flags: true, expunge: true };
|
|
94
|
+
|
|
95
|
+
async connect(uri: string): Promise<IMAPSession> { /* ... */ }
|
|
96
|
+
async request(session, context) { /* ... */ }
|
|
97
|
+
async disconnect(session) { /* ... */ }
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
const { transport } = imap('imap://server.com', new MyImapConnector());
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Documentation
|
|
104
|
+
|
|
105
|
+
Full documentation available at [unireq.dev](https://oorabona.github.io/unireq/)
|
|
106
|
+
|
|
107
|
+
## License
|
|
108
|
+
|
|
109
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@unireq/imap",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "IMAP transport for unireq using ImapFlow",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
"author": "Olivier Orabona",
|
|
18
18
|
"license": "MIT",
|
|
19
19
|
"dependencies": {
|
|
20
|
-
"@unireq/core": "1.0.
|
|
20
|
+
"@unireq/core": "1.0.1"
|
|
21
21
|
},
|
|
22
22
|
"peerDependencies": {
|
|
23
23
|
"imapflow": "^1.2.3"
|