@theokit/gateway-email 0.1.0
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/CHANGELOG.md +37 -0
- package/LICENSE +201 -0
- package/README.md +7 -0
- package/dist/index.cjs +551 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +144 -0
- package/dist/index.d.ts +144 -0
- package/dist/index.js +542 -0
- package/dist/index.js.map +1 -0
- package/package.json +56 -0
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { BasePlatformAdapter, OutboundMessage, SendResult, MessageEvent } from '@theokit/gateway';
|
|
2
|
+
export { EmailMessageEvent } from '@theokit/gateway';
|
|
3
|
+
|
|
4
|
+
/** Adapter options. */
|
|
5
|
+
interface EmailAdapterOptions {
|
|
6
|
+
/** Email address the bot listens on (also the From: of outbound). */
|
|
7
|
+
readonly address: string;
|
|
8
|
+
/** Password — for Gmail use an App Password (NOT the account password). */
|
|
9
|
+
readonly password: string;
|
|
10
|
+
/** IMAP server (e.g., "imap.gmail.com"). */
|
|
11
|
+
readonly imapHost: string;
|
|
12
|
+
/** IMAP port. Default 993 (SSL). */
|
|
13
|
+
readonly imapPort?: number;
|
|
14
|
+
/** SMTP server (e.g., "smtp.gmail.com"). */
|
|
15
|
+
readonly smtpHost: string;
|
|
16
|
+
/** SMTP port. Default 587 (STARTTLS). */
|
|
17
|
+
readonly smtpPort?: number;
|
|
18
|
+
/** Display name for outbound From: (defaults to address local-part). */
|
|
19
|
+
readonly fromName?: string;
|
|
20
|
+
/** Allowlist of sender addresses (case-insensitive). Default: open (D333). */
|
|
21
|
+
readonly allowedSenders?: readonly string[];
|
|
22
|
+
/** Allow automated senders (noreply, postmaster, bounce). Default: false (D332). */
|
|
23
|
+
readonly allowAutomated?: boolean;
|
|
24
|
+
/** Polling interval in ms when IMAP IDLE is unavailable. Default 15000. */
|
|
25
|
+
readonly pollIntervalMs?: number;
|
|
26
|
+
/** Max body chars before truncation (EC-2). Default 50000 (~12k tokens). */
|
|
27
|
+
readonly maxBodyChars?: number;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* `EmailAdapter` — Email platform adapter for `@theokit/gateway`
|
|
32
|
+
* (Adoption Roadmap v1.4 #4; ADRs D327-D339).
|
|
33
|
+
*
|
|
34
|
+
* Stack: nodemailer (SMTP) + imapflow (IMAP IDLE) + mailparser (RFC 5322).
|
|
35
|
+
* Inbound: IMAP IDLE preferred (D328), 15s poll fallback.
|
|
36
|
+
* Outbound: SMTP via nodemailer + threading reciprocity (D337).
|
|
37
|
+
*
|
|
38
|
+
* @public
|
|
39
|
+
*/
|
|
40
|
+
|
|
41
|
+
declare class EmailAdapter extends BasePlatformAdapter {
|
|
42
|
+
readonly platform: "email";
|
|
43
|
+
private readonly options;
|
|
44
|
+
private readonly seenUids;
|
|
45
|
+
private readonly threadStore;
|
|
46
|
+
private imap;
|
|
47
|
+
private smtp;
|
|
48
|
+
private handler?;
|
|
49
|
+
private connected;
|
|
50
|
+
private dispatchQueue;
|
|
51
|
+
private pollTimer;
|
|
52
|
+
constructor(opts: EmailAdapterOptions);
|
|
53
|
+
connect(): Promise<boolean>;
|
|
54
|
+
disconnect(): Promise<void>;
|
|
55
|
+
sendMessage(out: OutboundMessage): Promise<SendResult>;
|
|
56
|
+
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
57
|
+
/**
|
|
58
|
+
* EC-4: serialize concurrent IDLE dispatches so seen-check is atomic.
|
|
59
|
+
* Fire-and-forget: never throws; errors logged.
|
|
60
|
+
*/
|
|
61
|
+
private _dispatchInbound;
|
|
62
|
+
private _dispatchInboundInner;
|
|
63
|
+
get _threadStoreSize(): number;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Per-error → canonical `SendResult.error` mapping for email IMAP/SMTP failures.
|
|
68
|
+
*
|
|
69
|
+
* Tolerates plain `Error` without `.code`/`.responseCode` (EC-7 pattern from Teams).
|
|
70
|
+
*
|
|
71
|
+
* @internal
|
|
72
|
+
*/
|
|
73
|
+
interface ErrorPayload {
|
|
74
|
+
code: "auth_failed" | "rate_limit" | "invalid_request" | "server_error" | "not_connected" | "empty_text" | "timeout" | "unknown";
|
|
75
|
+
message: string;
|
|
76
|
+
}
|
|
77
|
+
declare function mapEmailError(err: unknown): ErrorPayload;
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Inbound filters: automated-sender (D332) + allowed-sender allowlist (D333 + EC-3).
|
|
81
|
+
*
|
|
82
|
+
* @internal
|
|
83
|
+
*/
|
|
84
|
+
/**
|
|
85
|
+
* EC-3: extract pure email address from a string that may include display
|
|
86
|
+
* name + brackets (`"Alice" <alice@example.com>`). Normalizes to lowercase.
|
|
87
|
+
*/
|
|
88
|
+
declare function extractAddr(s: string): string;
|
|
89
|
+
/**
|
|
90
|
+
* D332: automated-sender filter. Returns `true` if the message should be
|
|
91
|
+
* DROPPED (sender is automated / bot-loop risk).
|
|
92
|
+
*/
|
|
93
|
+
declare function isAutomatedSender(fromAddress: string, headers: Map<string, string>): boolean;
|
|
94
|
+
/**
|
|
95
|
+
* D333 + EC-3: allowed-sender allowlist.
|
|
96
|
+
*
|
|
97
|
+
* - `undefined` allowlist → OPEN (all allowed).
|
|
98
|
+
* - Empty array → CLOSED (none allowed). Intentional distinction from undefined.
|
|
99
|
+
* - Both sides normalized via `extractAddr` so `"Alice <alice@x>"` matches `alice@x`.
|
|
100
|
+
*/
|
|
101
|
+
declare function isAllowedSender(fromAddress: string, allowedSenders?: readonly string[]): boolean;
|
|
102
|
+
|
|
103
|
+
interface NormalizeOptions {
|
|
104
|
+
readonly botAddress: string;
|
|
105
|
+
/** EC-2: cap body length. Default 50000. */
|
|
106
|
+
readonly maxBodyChars?: number;
|
|
107
|
+
}
|
|
108
|
+
declare function normalizeEmail(rawBuffer: Buffer | string, opts: NormalizeOptions): Promise<EmailMessageEvent>;
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Bounded `Set<number>` of dispatched IMAP UIDs (ADR D331).
|
|
112
|
+
*
|
|
113
|
+
* Caps at 5000 entries; trims to 4000 (drops oldest 1000) on overflow.
|
|
114
|
+
* Same pattern as the Teams ConversationReferenceStore / WhatsApp Web bridge
|
|
115
|
+
* — bounded memory in long-running bots.
|
|
116
|
+
*
|
|
117
|
+
* @internal
|
|
118
|
+
*/
|
|
119
|
+
declare class SeenUidSet {
|
|
120
|
+
private set;
|
|
121
|
+
static readonly MAX_SIZE = 5000;
|
|
122
|
+
static readonly TRIM_TO = 4000;
|
|
123
|
+
has(uid: number): boolean;
|
|
124
|
+
add(uid: number): void;
|
|
125
|
+
private trim;
|
|
126
|
+
get size(): number;
|
|
127
|
+
clear(): void;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
interface ThreadContext {
|
|
131
|
+
readonly subject: string;
|
|
132
|
+
readonly references: readonly string[];
|
|
133
|
+
readonly lastMessageId: string;
|
|
134
|
+
}
|
|
135
|
+
declare class ThreadStore {
|
|
136
|
+
private readonly map;
|
|
137
|
+
static readonly MAX_SIZE = 1000;
|
|
138
|
+
recordFromInbound(event: EmailMessageEvent): void;
|
|
139
|
+
lookup(topicId: string): ThreadContext | undefined;
|
|
140
|
+
get size(): number;
|
|
141
|
+
clear(): void;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
export { EmailAdapter, type EmailAdapterOptions, type NormalizeOptions, SeenUidSet, type ThreadContext, ThreadStore, extractAddr, isAllowedSender, isAutomatedSender, mapEmailError, normalizeEmail };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { BasePlatformAdapter, OutboundMessage, SendResult, MessageEvent } from '@theokit/gateway';
|
|
2
|
+
export { EmailMessageEvent } from '@theokit/gateway';
|
|
3
|
+
|
|
4
|
+
/** Adapter options. */
|
|
5
|
+
interface EmailAdapterOptions {
|
|
6
|
+
/** Email address the bot listens on (also the From: of outbound). */
|
|
7
|
+
readonly address: string;
|
|
8
|
+
/** Password — for Gmail use an App Password (NOT the account password). */
|
|
9
|
+
readonly password: string;
|
|
10
|
+
/** IMAP server (e.g., "imap.gmail.com"). */
|
|
11
|
+
readonly imapHost: string;
|
|
12
|
+
/** IMAP port. Default 993 (SSL). */
|
|
13
|
+
readonly imapPort?: number;
|
|
14
|
+
/** SMTP server (e.g., "smtp.gmail.com"). */
|
|
15
|
+
readonly smtpHost: string;
|
|
16
|
+
/** SMTP port. Default 587 (STARTTLS). */
|
|
17
|
+
readonly smtpPort?: number;
|
|
18
|
+
/** Display name for outbound From: (defaults to address local-part). */
|
|
19
|
+
readonly fromName?: string;
|
|
20
|
+
/** Allowlist of sender addresses (case-insensitive). Default: open (D333). */
|
|
21
|
+
readonly allowedSenders?: readonly string[];
|
|
22
|
+
/** Allow automated senders (noreply, postmaster, bounce). Default: false (D332). */
|
|
23
|
+
readonly allowAutomated?: boolean;
|
|
24
|
+
/** Polling interval in ms when IMAP IDLE is unavailable. Default 15000. */
|
|
25
|
+
readonly pollIntervalMs?: number;
|
|
26
|
+
/** Max body chars before truncation (EC-2). Default 50000 (~12k tokens). */
|
|
27
|
+
readonly maxBodyChars?: number;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* `EmailAdapter` — Email platform adapter for `@theokit/gateway`
|
|
32
|
+
* (Adoption Roadmap v1.4 #4; ADRs D327-D339).
|
|
33
|
+
*
|
|
34
|
+
* Stack: nodemailer (SMTP) + imapflow (IMAP IDLE) + mailparser (RFC 5322).
|
|
35
|
+
* Inbound: IMAP IDLE preferred (D328), 15s poll fallback.
|
|
36
|
+
* Outbound: SMTP via nodemailer + threading reciprocity (D337).
|
|
37
|
+
*
|
|
38
|
+
* @public
|
|
39
|
+
*/
|
|
40
|
+
|
|
41
|
+
declare class EmailAdapter extends BasePlatformAdapter {
|
|
42
|
+
readonly platform: "email";
|
|
43
|
+
private readonly options;
|
|
44
|
+
private readonly seenUids;
|
|
45
|
+
private readonly threadStore;
|
|
46
|
+
private imap;
|
|
47
|
+
private smtp;
|
|
48
|
+
private handler?;
|
|
49
|
+
private connected;
|
|
50
|
+
private dispatchQueue;
|
|
51
|
+
private pollTimer;
|
|
52
|
+
constructor(opts: EmailAdapterOptions);
|
|
53
|
+
connect(): Promise<boolean>;
|
|
54
|
+
disconnect(): Promise<void>;
|
|
55
|
+
sendMessage(out: OutboundMessage): Promise<SendResult>;
|
|
56
|
+
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
57
|
+
/**
|
|
58
|
+
* EC-4: serialize concurrent IDLE dispatches so seen-check is atomic.
|
|
59
|
+
* Fire-and-forget: never throws; errors logged.
|
|
60
|
+
*/
|
|
61
|
+
private _dispatchInbound;
|
|
62
|
+
private _dispatchInboundInner;
|
|
63
|
+
get _threadStoreSize(): number;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Per-error → canonical `SendResult.error` mapping for email IMAP/SMTP failures.
|
|
68
|
+
*
|
|
69
|
+
* Tolerates plain `Error` without `.code`/`.responseCode` (EC-7 pattern from Teams).
|
|
70
|
+
*
|
|
71
|
+
* @internal
|
|
72
|
+
*/
|
|
73
|
+
interface ErrorPayload {
|
|
74
|
+
code: "auth_failed" | "rate_limit" | "invalid_request" | "server_error" | "not_connected" | "empty_text" | "timeout" | "unknown";
|
|
75
|
+
message: string;
|
|
76
|
+
}
|
|
77
|
+
declare function mapEmailError(err: unknown): ErrorPayload;
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Inbound filters: automated-sender (D332) + allowed-sender allowlist (D333 + EC-3).
|
|
81
|
+
*
|
|
82
|
+
* @internal
|
|
83
|
+
*/
|
|
84
|
+
/**
|
|
85
|
+
* EC-3: extract pure email address from a string that may include display
|
|
86
|
+
* name + brackets (`"Alice" <alice@example.com>`). Normalizes to lowercase.
|
|
87
|
+
*/
|
|
88
|
+
declare function extractAddr(s: string): string;
|
|
89
|
+
/**
|
|
90
|
+
* D332: automated-sender filter. Returns `true` if the message should be
|
|
91
|
+
* DROPPED (sender is automated / bot-loop risk).
|
|
92
|
+
*/
|
|
93
|
+
declare function isAutomatedSender(fromAddress: string, headers: Map<string, string>): boolean;
|
|
94
|
+
/**
|
|
95
|
+
* D333 + EC-3: allowed-sender allowlist.
|
|
96
|
+
*
|
|
97
|
+
* - `undefined` allowlist → OPEN (all allowed).
|
|
98
|
+
* - Empty array → CLOSED (none allowed). Intentional distinction from undefined.
|
|
99
|
+
* - Both sides normalized via `extractAddr` so `"Alice <alice@x>"` matches `alice@x`.
|
|
100
|
+
*/
|
|
101
|
+
declare function isAllowedSender(fromAddress: string, allowedSenders?: readonly string[]): boolean;
|
|
102
|
+
|
|
103
|
+
interface NormalizeOptions {
|
|
104
|
+
readonly botAddress: string;
|
|
105
|
+
/** EC-2: cap body length. Default 50000. */
|
|
106
|
+
readonly maxBodyChars?: number;
|
|
107
|
+
}
|
|
108
|
+
declare function normalizeEmail(rawBuffer: Buffer | string, opts: NormalizeOptions): Promise<EmailMessageEvent>;
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Bounded `Set<number>` of dispatched IMAP UIDs (ADR D331).
|
|
112
|
+
*
|
|
113
|
+
* Caps at 5000 entries; trims to 4000 (drops oldest 1000) on overflow.
|
|
114
|
+
* Same pattern as the Teams ConversationReferenceStore / WhatsApp Web bridge
|
|
115
|
+
* — bounded memory in long-running bots.
|
|
116
|
+
*
|
|
117
|
+
* @internal
|
|
118
|
+
*/
|
|
119
|
+
declare class SeenUidSet {
|
|
120
|
+
private set;
|
|
121
|
+
static readonly MAX_SIZE = 5000;
|
|
122
|
+
static readonly TRIM_TO = 4000;
|
|
123
|
+
has(uid: number): boolean;
|
|
124
|
+
add(uid: number): void;
|
|
125
|
+
private trim;
|
|
126
|
+
get size(): number;
|
|
127
|
+
clear(): void;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
interface ThreadContext {
|
|
131
|
+
readonly subject: string;
|
|
132
|
+
readonly references: readonly string[];
|
|
133
|
+
readonly lastMessageId: string;
|
|
134
|
+
}
|
|
135
|
+
declare class ThreadStore {
|
|
136
|
+
private readonly map;
|
|
137
|
+
static readonly MAX_SIZE = 1000;
|
|
138
|
+
recordFromInbound(event: EmailMessageEvent): void;
|
|
139
|
+
lookup(topicId: string): ThreadContext | undefined;
|
|
140
|
+
get size(): number;
|
|
141
|
+
clear(): void;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
export { EmailAdapter, type EmailAdapterOptions, type NormalizeOptions, SeenUidSet, type ThreadContext, ThreadStore, extractAddr, isAllowedSender, isAutomatedSender, mapEmailError, normalizeEmail };
|